# 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:

```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...",
        "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

```bash
# 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:

```bash
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

```javascript
// 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

```bash
# 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:

```javascript
// 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.

### Label Management

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

**Claude** will use the `list_labels` tool to fetch all repository labels.

---

**You**: "Create a new label called 'bug' with red color (#ff0000) in owner/repo"

**Claude** will use the `create_label` tool to create the label.

---

**You**: "Get details about label ID 3 in owner/repo"

**Claude** will use the `get_label` tool to fetch the label information.

---

**You**: "Update label ID 3 in owner/repo to change its name to 'critical-bug' and color to #cc0000"

**Claude** will use the `update_label` tool to modify the label.

---

**You**: "Delete label ID 5 from owner/repo"

**Claude** will use the `delete_label` tool to remove the label.

---

**You**: "What labels are on issue #7 in owner/repo?"

**Claude** will use the `list_issue_labels` tool to fetch labels on the specific issue.

---

**You**: "Add labels 3 and 5 to issue #7 in owner/repo"

**Claude** will use the `add_issue_labels` tool to add the specified labels to the issue.

---

**You**: "Remove label ID 3 from issue #7 in owner/repo"

**Claude** will use the `remove_issue_label` tool to remove that specific label.

---

**You**: "Replace all labels on issue #7 with labels 4 and 6"

**Claude** will use the `replace_issue_labels` tool to set exactly those labels on the issue.

---

**You**: "Remove all labels from issue #7 in owner/repo"

**Claude** will use the `remove_all_issue_labels` tool to clear all labels from 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.