gogs-mcp/USAGE_EXAMPLES.md

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:

{
  "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.