Document HTTP transport and issue management features #2

Updated documentation to reflect the complete feature set including
HTTP transport support and issue management capabilities.

Changes:
- Added Issue Management section to README features
- Documented all issue management tools (list, get, create, update, comments)
- Added HTTP transport configuration and usage examples
- Updated USAGE_EXAMPLES.md with HTTP setup instructions
- Added MCP Client SDK integration examples for HTTP mode
- Added issue management usage examples
- Included HTTP endpoint testing examples with curl

This completes the documentation for issue #2.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

README.md

@@ -24,6 +24,15 @@ This MCP server provides tools to:
   - List repository branches
   - Get commit history
 
+- **Issue Management**
+  - List issues in a repository
+  - Get specific issue details
+  - Create new issues
+  - Update existing issues (including state changes)
+  - List comments on issues
+  - Add comments to issues
+  - Edit existing comments
+
 ## Installation
 
 ### Prerequisites
@@ -101,6 +110,13 @@ Create a `.env` file or set environment variables:
 ```bash
 GOGS_SERVER_URL=https://your-gogs-server.com
 GOGS_ACCESS_TOKEN=your-access-token-here
+
+# Transport mode (optional, default: stdio)
+TRANSPORT_MODE=stdio  # or 'http' for HTTP/SSE transport
+
+# HTTP server configuration (only used when TRANSPORT_MODE=http)
+HTTP_PORT=3000
+HTTP_HOST=0.0.0.0
 ```
 
 The access token is optional but recommended. Without it:
@@ -108,9 +124,24 @@ The access token is optional but recommended. Without it:
 - Some operations requiring authentication will fail
 - Only public repositories will be accessible
 
+### Transport Modes
+
+The server supports two transport modes:
+
+**stdio (default)**: For use with MCP clients like Claude Desktop
+- Communicates via standard input/output
+- Runs as a subprocess of the MCP client
+- Suitable for desktop applications
+
+**http**: For HTTP-based access with Server-Sent Events (SSE)
+- Exposes HTTP endpoints for the MCP protocol
+- Runs as a standalone web server
+- Suitable for web applications and remote access
+- Supports CORS for cross-origin requests
+
 ## Usage
 
-### With Claude Desktop
+### With Claude Desktop (stdio mode)
 
 Add the server to your Claude Desktop configuration file:
 
@@ -125,14 +156,57 @@ Add the server to your Claude Desktop configuration file:
       "args": ["/absolute/path/to/gogs-mcp-server/dist/index.js"],
       "env": {
         "GOGS_SERVER_URL": "https://your-gogs-server.com",
-        "GOGS_ACCESS_TOKEN": "your-access-token-here"
+        "GOGS_ACCESS_TOKEN": "your-access-token-here",
+        "TRANSPORT_MODE": "stdio"
       }
     }
   }
 }
 ```
 
-### With Other MCP Clients
+### HTTP Mode
+
+To run the server in HTTP mode for web applications:
+
+1. Set the transport mode to HTTP in your `.env` file:
+   ```bash
+   TRANSPORT_MODE=http
+   HTTP_PORT=3000
+   HTTP_HOST=0.0.0.0
+   ```
+
+2. Start the server:
+   ```bash
+   npm start
+   ```
+
+3. The server will be available at:
+   - SSE endpoint: `http://localhost:3000/sse`
+   - Message endpoint: `http://localhost:3000/message`
+   - Health check: `http://localhost:3000/health`
+
+4. Connect your MCP client to the SSE endpoint to establish a persistent connection.
+
+### HTTP Mode with Docker
+
+```bash
+# Set environment variables in .env
+TRANSPORT_MODE=http
+HTTP_PORT=3000
+
+# Run with docker-compose
+docker-compose up -d
+
+# Or run with Docker directly
+docker run -p 3000:3000 \
+  -e GOGS_SERVER_URL=https://your-gogs-server.com \
+  -e GOGS_ACCESS_TOKEN=your-access-token-here \
+  -e TRANSPORT_MODE=http \
+  -e HTTP_PORT=3000 \
+  gogs-mcp-server:latest
+```
+
+### With Other MCP Clients (stdio mode)
 
 The server uses stdio transport and can be integrated with any MCP-compatible client:
 
@@ -140,6 +214,7 @@ The server uses stdio transport and can be integrated with any MCP-compatible cl
 # Set environment variables
 export GOGS_SERVER_URL=https://your-gogs-server.com
 export GOGS_ACCESS_TOKEN=your-access-token-here
+export TRANSPORT_MODE=stdio
 
 # Run the server
 npm start
@@ -262,6 +337,65 @@ Get commit history from a repository.
 - `sha` (string, optional): Branch name or commit SHA
 - `page` (number, optional): Page number (default: 1)
 
+### Issue Management Tools
+
+#### `list_issues`
+List issues in a repository.
+- `owner` (string, required): Repository owner username
+- `repo` (string, required): Repository name
+- `state` (string, optional): Filter by state - 'open', 'closed', or 'all' (default: 'open')
+- `labels` (string, optional): Comma-separated list of label names
+- `page` (number, optional): Page number (default: 1)
+- `per_page` (number, optional): Results per page (default: 30)
+
+#### `get_issue`
+Get a specific issue by number.
+- `owner` (string, required): Repository owner username
+- `repo` (string, required): Repository name
+- `number` (number, required): Issue number
+
+#### `create_issue`
+Create a new issue in a repository.
+- `owner` (string, required): Repository owner username
+- `repo` (string, required): Repository name
+- `title` (string, required): Issue title
+- `body` (string, optional): Issue description
+- `assignee` (string, optional): Username to assign the issue to
+- `milestone` (number, optional): Milestone ID
+- `labels` (array of numbers, optional): Array of label IDs
+
+#### `update_issue`
+Update an existing issue (including closing or reopening).
+- `owner` (string, required): Repository owner username
+- `repo` (string, required): Repository name
+- `number` (number, required): Issue number
+- `title` (string, optional): Issue title
+- `body` (string, optional): Issue description
+- `assignee` (string, optional): Username to assign the issue to
+- `milestone` (number, optional): Milestone ID
+- `state` (string, optional): Issue state - 'open' or 'closed'
+- `labels` (array of numbers, optional): Array of label IDs
+
+#### `list_issue_comments`
+List all comments on an issue.
+- `owner` (string, required): Repository owner username
+- `repo` (string, required): Repository name
+- `number` (number, required): Issue number
+
+#### `create_issue_comment`
+Add a comment to an issue.
+- `owner` (string, required): Repository owner username
+- `repo` (string, required): Repository name
+- `number` (number, required): Issue number
+- `body` (string, required): Comment text
+
+#### `update_issue_comment`
+Edit an existing comment on an issue.
+- `owner` (string, required): Repository owner username
+- `repo` (string, required): Repository name
+- `commentId` (number, required): Comment ID
+- `body` (string, required): Updated comment text
+
 ## Development
 
 ### Run in Development Mode

USAGE_EXAMPLES.md

@@ -2,7 +2,9 @@
 
 This document provides practical examples of using the Gogs MCP Server with AI assistants like Claude.
 
-## Setup Example
+## Setup Examples
+
+### stdio Transport (Claude Desktop)
 
 Once configured in Claude Desktop, you can interact naturally with your Gogs server:
 
@@ -14,13 +16,113 @@ Once configured in Claude Desktop, you can interact naturally with your Gogs ser
       "args": ["/path/to/gogs-mcp-server/dist/index.js"],
       "env": {
         "GOGS_SERVER_URL": "https://gogs.example.com",
-        "GOGS_ACCESS_TOKEN": "abc123..."
+        "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
@@ -111,6 +213,42 @@ Once configured in Claude Desktop, you can interact naturally with your Gogs ser
 
 **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