# Gogs MCP Server Usage Examples

This document provides practical examples of using the Gogs MCP Server with AI assistants like Claude.

## Setup Example

Once configured in Claude Desktop, you can interact naturally with your Gogs server:

```json
{
  "mcpServers": {
    "gogs": {
      "command": "node",
      "args": ["/path/to/gogs-mcp-server/dist/index.js"],
      "env": {
        "GOGS_SERVER_URL": "https://gogs.example.com",
        "GOGS_ACCESS_TOKEN": "abc123..."
      }
    }
  }
}
```

## Example Conversations

### Exploring Repositories

**You**: "List all my repositories on Gogs"

**Claude** will use the `list_user_repositories` tool to fetch your repositories and present them in a readable format.

---

**You**: "Search for repositories containing 'docker' in their name"

**Claude** will use the `search_repositories` tool with query "docker" and show results.

---

**You**: "Show me information about the repository user/my-project"

**Claude** will use the `get_repository` tool to fetch and display repository details.

### Reading Code

**You**: "Show me the contents of README.md from owner/repo"

**Claude** will use the `get_contents` tool to fetch and display the file contents.

---

**You**: "Get the raw content of src/main.go from the develop branch of owner/repo"

**Claude** will use the `get_raw_content` tool with the specified parameters.

---

**You**: "What files are in the src/ directory of owner/repo?"

**Claude** will use the `get_contents` tool to list directory contents.

### Repository Management

**You**: "Create a new repository called 'test-project' with description 'My test project'"

**Claude** will use the `create_repository` tool to create the repository.

---

**You**: "Create a private Go repository with MIT license and appropriate gitignore"

**Claude** will use the `create_repository` tool with:
- `private: true`
- `license: "MIT License"`
- `gitignores: "Go"`
- `auto_init: true`

### Branch and Commit History

**You**: "List all branches in owner/repo"

**Claude** will use the `list_branches` tool to fetch branch information.

---

**You**: "Show me the recent commits from the main branch of owner/repo"

**Claude** will use the `get_commits` tool to fetch commit history.

---

**You**: "What are the latest 5 commits on the develop branch?"

**Claude** will use the `get_commits` tool with `sha: "develop"` to get recent commits.

### User Management

**You**: "Search for users named 'john'"

**Claude** will use the `search_users` tool with query "john".

---

**You**: "Get information about user 'johndoe'"

**Claude** will use the `get_user` tool to fetch user details.

---

**You**: "Who am I logged in as?"

**Claude** will use the `get_current_user` tool to show your authenticated user info.

## Complex Workflows

### Code Review Workflow

**You**: "Review the latest changes in owner/repo on the feature-branch branch"

**Claude** will:
1. Use `get_commits` to fetch recent commits from feature-branch
2. Use `get_contents` to read modified files
3. Provide analysis and feedback on the code

### Repository Analysis

**You**: "Analyze the structure of owner/repo and tell me what kind of project it is"

**Claude** will:
1. Use `get_repository` to get basic info
2. Use `get_contents` to explore root directory
3. Use `get_contents` or `get_raw_content` to read key files (package.json, go.mod, etc.)
4. Analyze and describe the project structure and type

### Migration Planning

**You**: "I want to migrate my project from GitHub to Gogs. Can you help me create the repository?"

**Claude** will:
1. Ask for necessary details (repository name, description, etc.)
2. Use `create_repository` with appropriate parameters
3. Provide instructions for pushing code to the new repository

## Tips for Effective Use

### Be Specific
Instead of: "Look at that file"
Use: "Show me the contents of src/main.go from the master branch of owner/repo"

### Use Natural Language
The MCP server allows natural interaction. You can say:
- "Find repositories about kubernetes"
- "What's in the config directory?"
- "Create a new private Python project"

### Combine Operations
You can ask Claude to perform multiple operations:
- "List all branches in owner/repo and show me the latest commit on each"
- "Search for all repositories by user 'alice' and tell me which ones are private"

### Context Awareness
Claude can maintain context across multiple queries:
- "List my repositories" → "Tell me more about the second one" → "Show me its README"

## Error Handling

If you encounter errors, Claude will explain them:

- **404 Not Found**: Repository or user doesn't exist, or you don't have access
- **401 Unauthorized**: Authentication required or token is invalid
- **Environment variable not set**: Configuration issue with the MCP server

## Performance Considerations

- Large file contents are automatically decoded and presented
- Directory listings show all contents at once
- Commit history is paginated (use the `page` parameter for more commits)
- Search results are limited by default (use `limit` parameter to adjust)

## Security Notes

When using the MCP server:
- Your access token provides the same permissions as using the Gogs web interface
- All operations are logged on the Gogs server
- Be cautious with delete operations - they cannot be undone
- Private repository access requires authentication

## Advanced Examples

### Finding a Specific Function

**You**: "Search through the codebase of owner/repo for the function 'handleRequest'"

**Claude** will:
1. Use `get_contents` to explore directories
2. Use `get_raw_content` to read likely files
3. Search for the function and show its location and implementation

### Comparing Branches

**You**: "What are the differences between the main and develop branches in owner/repo?"

**Claude** will:
1. Use `get_commits` on both branches
2. Identify differing commits
3. Summarize the differences

### Repository Setup Automation

**You**: "Create a new Node.js repository with TypeScript setup, MIT license, and Node.js gitignore"

**Claude** will use `create_repository` with:
```
{
  "name": "<project-name>",
  "description": "TypeScript Node.js project",
  "auto_init": true,
  "gitignores": "Node",
  "license": "MIT License"
}
```

Then provide instructions for setting up TypeScript configuration locally.