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 Examples

stdio Transport (Claude Desktop)

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...",
        "TRANSPORT_MODE": "stdio"
      }
    }
  }
}

HTTP Transport (Web Applications)

For web-based MCP clients or remote access, run the server in HTTP mode:

Starting the HTTP Server

# Set environment variables
export GOGS_SERVER_URL=https://gogs.example.com
export GOGS_ACCESS_TOKEN=abc123...
export TRANSPORT_MODE=http
export HTTP_PORT=3000
export HTTP_HOST=0.0.0.0

# Start the server
npm start

Or with Docker:

docker run -p 3000:3000 \
  -e GOGS_SERVER_URL=https://gogs.example.com \
  -e GOGS_ACCESS_TOKEN=abc123... \
  -e TRANSPORT_MODE=http \
  -e HTTP_PORT=3000 \
  -e HTTP_HOST=0.0.0.0 \
  gogs-mcp-server:latest

Connecting to HTTP Server

The HTTP server exposes three endpoints:

• SSE Endpoint: http://localhost:3000/sse - Establishes SSE connection for MCP protocol
• Message Endpoint: http://localhost:3000/message - Receives client messages
• Health Check: http://localhost:3000/health - Server health status

Using HTTP Transport with MCP Client Libraries

// Example using MCP Client SDK with HTTP transport
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { SSEClientTransport } from '@modelcontextprotocol/sdk/client/sse.js';

// Connect to the HTTP server
const transport = new SSEClientTransport(
  new URL('http://localhost:3000/sse')
);

const client = new Client(
  {
    name: 'my-client',
    version: '1.0.0',
  },
  {
    capabilities: {},
  }
);

await client.connect(transport);

// Now you can call tools
const result = await client.callTool({
  name: 'get_current_user',
  arguments: {},
});

console.log(result);

Testing HTTP Endpoints

# Check server health
curl http://localhost:3000/health

# Expected response:
# {"status":"ok","service":"gogs-mcp-server","transport":"http"}

# Connect to SSE endpoint
curl -N http://localhost:3000/sse

# Expected response (SSE stream):
# event: endpoint
# data: /message?sessionId=<uuid>

CORS Support

The HTTP server includes CORS support, allowing cross-origin requests from web applications:

// Example from a web application
const response = await fetch('http://localhost:3000/health');
const data = await response.json();
console.log(data); // {"status":"ok",...}

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.

Issue Management

You: "List all open issues in owner/repo"

Claude will use the list_issues tool to fetch open issues.

---

You: "Show me issue #5 from owner/repo"

Claude will use the get_issue tool with number 5 to fetch issue details.

---

You: "Create an issue in owner/repo titled 'Fix login bug' with description 'Users cannot login'"

Claude will use the create_issue tool to create a new issue.

---

You: "Add a comment to issue #5 in owner/repo saying 'Working on this now'"

Claude will use the create_issue_comment tool to add the comment.

---

You: "List all comments on issue #5 in owner/repo"

Claude will use the list_issue_comments tool to fetch comments.

---

You: "Close issue #5 in owner/repo"

Claude will use the update_issue tool with state: "closed" to close the issue.

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.