personal-projects/gitea-mcp-remote
1
0
Fork 0
generated from personal-projects/leo-claude-mktplace
Code Issues 2 Pull Requests Actions Packages Projects Releases Wiki Activity

docs: Create CLAUDE.md and update deployment documentation (#27)

Browse Source 
- Create CLAUDE.md with comprehensive project guidance for Claude Code
- Update README.md with correct architecture (direct import, not subprocess)
- Update project structure to reflect tests/ at repo root and docker/ directory
- Update default port from 8000 to 8080
- Update repository links to Gitea
- Update DEPLOYMENT.md with two-service Docker architecture (app + Caddy)
- Fix Claude Desktop config example to use /mcp endpoint

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Leo Miranda
2026-02-03 21:32:39 -05:00
parent 88c16c840b
commit 2dbb66deae
3 changed files with 354 additions and 81 deletions
Download Patch File Download Diff File Expand all files Collapse all files

239
CLAUDE.md Normal file
View File

@@ -0,0 +1,239 @@
# CLAUDE.md - Gitea MCP Remote
This file provides guidance to Claude Code when working with this repository.
## Project Overview
**Name:** gitea-mcp-remote
**Type:** HTTP transport server for MCP (Model Context Protocol)
**Purpose:** Expose Gitea operations via MCP Streamable HTTP protocol for AI assistants
This is NOT a standalone MCP server. It imports tools from the `gitea-mcp-server` marketplace package and serves them over HTTP with authentication and tool filtering.
## Architecture
```
Client (Claude Desktop) ──HTTP──▶ gitea-mcp-remote ──imports──▶ gitea-mcp-server ──API──▶ Gitea
│
├── Authentication (Bearer token)
├── Tool Filtering (enable/disable)
└── MCP Streamable HTTP protocol
```
**Key Design Decision:** This server uses direct imports from the marketplace `gitea-mcp-server` package, NOT subprocess spawning. Tool definitions and dispatchers are imported and used directly.
## Project Structure
```
gitea-mcp-remote/
├── src/gitea_mcp_remote/ # Main package
│ ├── __init__.py
│ ├── server_http.py # MCP HTTP server (main module)
│ ├── config/ # Configuration module
│ │ ├── __init__.py
│ │ └── settings.py # Pydantic settings loader
│ ├── middleware/ # HTTP middleware
│ │ ├── __init__.py
│ │ └── auth.py # Bearer auth + health check bypass
│ └── filtering/ # Tool filtering
│ ├── __init__.py
│ └── filter.py # Whitelist/blacklist filtering
├── tests/ # Test suite (at repo root)
│ ├── conftest.py
│ ├── test_config.py
│ ├── test_middleware.py
│ ├── test_filtering.py
│ └── test_mcp_endpoints.py
├── docker/ # Docker infrastructure
│ ├── Dockerfile # Multi-stage build
│ ├── docker-compose.yml # App + Caddy services
│ ├── Caddyfile # Reverse proxy config
│ └── .env.example # Environment template
├── scripts/ # Utility scripts
│ ├── start.sh # Production startup
│ └── healthcheck.sh # Docker health check
├── docs/ # Documentation
│ └── sprint-proposals/ # Sprint planning docs
├── pyproject.toml # Project configuration
├── requirements.txt # Dependencies
├── README.md # User documentation
├── DEPLOYMENT.md # Deployment guide
└── CLAUDE.md # This file
```
## Development Workflows
### Setup Development Environment
```bash
# Create virtual environment
python -m venv .venv
source .venv/bin/activate
# Install with development dependencies
pip install -e ".[dev]"
```
### Running Tests
```bash
# All tests
pytest tests/ -v
# With coverage
pytest tests/ --cov=gitea_mcp_remote
# Specific test file
pytest tests/test_mcp_endpoints.py -v
```
### Running the Server Locally
```bash
# Set required environment variables
export GITEA_URL=https://gitea.example.com
export GITEA_TOKEN=your_token
export GITEA_OWNER=your_org
# Run server
gitea-mcp-remote
```
### Docker Development
```bash
# Build and run
docker-compose -f docker/docker-compose.yml up --build
# Validate configuration
docker-compose -f docker/docker-compose.yml config
# Check logs
docker-compose -f docker/docker-compose.yml logs -f
```
## Key Files
### server_http.py
The main MCP server implementation:
- Imports tools from `mcp_server` (marketplace package)
- Creates `Server` instance with tool handlers
- Uses `StreamableHTTPServerTransport` for MCP protocol
- Health endpoint at `/health` (bypasses auth)
- MCP endpoint at `/mcp` (POST for requests, HEAD for protocol version)
### config/settings.py
Pydantic settings with:
- `gitea_url`, `gitea_token`, `gitea_owner` (required)
- `gitea_repo` (optional)
- `http_host` (default: 0.0.0.0), `http_port` (default: 8080)
- `auth_token` (optional Bearer token)
- `mcp_auth_mode` (optional/required/none)
- `enabled_tools`, `disabled_tools` (comma-separated)
### middleware/auth.py
Two middleware classes:
- `BearerAuthMiddleware`: Validates Authorization header
- `HealthCheckBypassMiddleware`: Sets `skip_auth` flag for health endpoints
**Important:** Middleware order matters. HealthCheckBypass must wrap BearerAuth (outermost) so it runs first.
## MCP Protocol Notes
This server implements the MCP Streamable HTTP protocol:
1. **HEAD /mcp** - Returns protocol version header (`x-mcp-protocol-version: 2024-11-05`)
2. **POST /mcp** - Accepts JSON-RPC 2.0 requests, returns SSE responses
Supported methods:
- `initialize` - Protocol handshake
- `tools/list` - List available tools
- `tools/call` - Execute a tool
### Request Format
```json
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "list_issues",
"arguments": {"owner": "org", "repo": "repo", "state": "open"}
}
}
```
### Response Format (SSE)
```
event: message
data: {"jsonrpc":"2.0","id":1,"result":[...]}
```
## Configuration Reference
| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| GITEA_URL | Yes | - | Gitea instance URL |
| GITEA_TOKEN | Yes | - | Gitea API token |
| GITEA_OWNER | Yes | - | Default owner/org |
| GITEA_REPO | No | None | Default repository |
| HTTP_HOST | No | 0.0.0.0 | Server bind address |
| HTTP_PORT | No | 8080 | Server port |
| AUTH_TOKEN | No | None | Bearer token for auth |
| MCP_AUTH_MODE | No | optional | Auth mode |
| ENABLED_TOOLS | No | None | Whitelist (comma-sep) |
| DISABLED_TOOLS | No | None | Blacklist (comma-sep) |
## Troubleshooting
### Import Errors from mcp_server
If `from mcp_server import ...` fails:
1. Verify `gitea-mcp-server` is installed: `pip list | grep gitea`
2. The package is installed from Git via pyproject.toml dependency
3. Reinstall: `pip install -e .`
### Health Endpoint Returns 401
Middleware order is wrong. HealthCheckBypassMiddleware must be outermost:
```python
if settings.auth_token:
app = BearerAuthMiddleware(app, auth_token=settings.auth_token)
app = HealthCheckBypassMiddleware(app) # Must be last (outermost)
```
### Tests Not Found
Ensure pyproject.toml has correct testpaths:
```toml
[tool.pytest.ini_options]
testpaths = ["tests"]
```
### MCP Requests Fail with 406
Missing Accept header. Requests must include:
```
Accept: application/json, text/event-stream
```
## Dependencies
**Runtime:**
- `gitea-mcp-server` - Marketplace package (Git dependency)
- `mcp` - MCP SDK
- `uvicorn` - ASGI server
- `starlette` - Web framework
- `pydantic-settings` - Configuration
**Development:**
- `pytest` - Testing
- `pytest-asyncio` - Async test support
- `pytest-cov` - Coverage
- `httpx` - HTTP client for tests

76
DEPLOYMENT.md
View File

@@ -1,6 +1,6 @@
# Deployment Guide # Deployment Guide
This guide covers production deployment of the Gitea HTTP MCP Wrapper in various environments. This guide covers production deployment of Gitea MCP Remote in various environments.
## Table of Contents ## Table of Contents
@@ -36,15 +36,15 @@ This guide covers production deployment of the Gitea HTTP MCP Wrapper in various
1. **Clone the repository:** 1. **Clone the repository:**
```bash ```bash
git clone https://github.com/lmiranda/gitea-mcp-remote.git git clone https://gitea.hotserv.cloud/personal-projects/gitea-mcp-remote.git
cd gitea-mcp-remote cd gitea-mcp-remote
``` ```
2. **Create configuration:** 2. **Create configuration:**
```bash ```bash
cp .env.docker.example .env cp docker/.env.example docker/.env
nano .env # Edit with your values nano docker/.env # Edit with your values
``` ```
Required configuration: Required configuration:
@@ -52,49 +52,49 @@ Required configuration:
GITEA_URL=https://gitea.example.com GITEA_URL=https://gitea.example.com
GITEA_TOKEN=your_gitea_api_token GITEA_TOKEN=your_gitea_api_token
GITEA_OWNER=your_username_or_org GITEA_OWNER=your_username_or_org
GITEA_REPO=your_default_repo GITEA_REPO=your_default_repo # Optional
AUTH_TOKEN=your_bearer_token # Recommended AUTH_TOKEN=your_bearer_token # Recommended
``` ```
3. **Start the service:** 3. **Start the services (app + Caddy):**
```bash ```bash
docker-compose up -d docker-compose -f docker/docker-compose.yml up -d
``` ```
4. **Verify deployment:** 4. **Verify deployment:**
```bash ```bash
curl http://localhost:8000/health curl http://localhost/health # Via Caddy
curl http://localhost:8080/health # Direct to app
``` ```
### Production Configuration ### Production Configuration
For production, use a more robust `docker-compose.yml`: The default `docker/docker-compose.yml` includes both app and Caddy reverse proxy services. For customization:
```yaml ```yaml
version: '3.8'
services: services:
gitea-mcp-wrapper: # Python MCP Server
app:
build: build:
context: . context: ..
dockerfile: Dockerfile dockerfile: docker/Dockerfile
image: gitea-mcp-wrapper:latest image: gitea-mcp-remote:latest
container_name: gitea-mcp-wrapper container_name: gitea-mcp-remote-app
restart: always restart: always
ports: expose:
- "127.0.0.1:8000:8000" # Bind to localhost only - "8080"
environment: environment:
- GITEA_URL=${GITEA_URL} - GITEA_URL=${GITEA_URL}
- GITEA_TOKEN=${GITEA_TOKEN} - GITEA_TOKEN=${GITEA_TOKEN}
- GITEA_OWNER=${GITEA_OWNER} - GITEA_OWNER=${GITEA_OWNER}
- GITEA_REPO=${GITEA_REPO} - GITEA_REPO=${GITEA_REPO:-}
- HTTP_HOST=0.0.0.0 - HTTP_HOST=0.0.0.0
- HTTP_PORT=8000 - HTTP_PORT=8080
- AUTH_TOKEN=${AUTH_TOKEN} - AUTH_TOKEN=${AUTH_TOKEN:-}
healthcheck: healthcheck:
test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:8000/health').read()"] test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
interval: 30s interval: 30s
timeout: 3s timeout: 3s
retries: 3 retries: 3
@@ -107,9 +107,31 @@ services:
networks: networks:
- gitea-mcp-network - gitea-mcp-network
# Caddy Reverse Proxy (HTTPS termination)
caddy:
image: caddy:2-alpine
container_name: gitea-mcp-remote-caddy
restart: always
ports:
- "80:80"
- "443:443"
volumes:
- ./Caddyfile:/etc/caddy/Caddyfile:ro
- caddy_data:/data
- caddy_config:/config
depends_on:
app:
condition: service_healthy
networks:
- gitea-mcp-network
networks: networks:
gitea-mcp-network: gitea-mcp-network:
driver: bridge driver: bridge
volumes:
caddy_data:
caddy_config:
``` ```
### Docker Build Options ### Docker Build Options
@@ -117,20 +139,20 @@ networks:
**Build the image:** **Build the image:**
```bash ```bash
docker build -t gitea-mcp-wrapper:latest . docker build -f docker/Dockerfile -t gitea-mcp-remote:latest .
``` ```
**Build with specific Python version:** **Build with specific Python version:**
```bash ```bash
docker build --build-arg PYTHON_VERSION=3.11 -t gitea-mcp-wrapper:latest . docker build -f docker/Dockerfile --build-arg PYTHON_VERSION=3.11 -t gitea-mcp-remote:latest .
``` ```
**Tag for registry:** **Tag for registry:**
```bash ```bash
docker tag gitea-mcp-wrapper:latest registry.example.com/gitea-mcp-wrapper:latest docker tag gitea-mcp-remote:latest registry.example.com/gitea-mcp-remote:latest
docker push registry.example.com/gitea-mcp-wrapper:latest docker push registry.example.com/gitea-mcp-remote:latest
``` ```
## Security Best Practices ## Security Best Practices
@@ -218,7 +240,7 @@ Docker automatically monitors the health check and can restart if unhealthy:
```yaml ```yaml
healthcheck: healthcheck:
test: ["CMD", "curl", "-f", "http://localhost:8000/health"] test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
interval: 30s interval: 30s
timeout: 3s timeout: 3s
retries: 3 retries: 3

110
README.md
View File

@@ -1,18 +1,22 @@
# Gitea HTTP MCP Wrapper # Gitea MCP Remote
An HTTP transport wrapper around the official Gitea MCP server that enables AI assistants like Claude Desktop to interact with Gitea repositories via HTTP. This wrapper provides authentication, tool filtering, and HTTP transport while delegating Gitea operations to the official `gitea-mcp-server`. An HTTP transport server that exposes Gitea operations via the MCP Streamable HTTP protocol for AI assistants like Claude Desktop. This server imports tools from the marketplace `gitea-mcp-server` package and serves them over HTTP with authentication and tool filtering.
## Architecture ## Architecture
This is NOT a standalone MCP server. It's an HTTP wrapper that: This is NOT a standalone MCP server. It imports tool definitions from the marketplace package and serves them:
1. Wraps the official `gitea-mcp-server` (stdio transport) 1. Imports tools from `gitea-mcp-server` marketplace package
2. Provides HTTP transport for Claude Desktop compatibility 2. Serves via MCP Streamable HTTP protocol (`/mcp` endpoint)
3. Adds Bearer token authentication 3. Adds Bearer token authentication (optional)
4. Filters tools for Claude Desktop compatibility 4. Provides tool filtering (whitelist/blacklist)
5. Proxies requests between HTTP and stdio transport 5. Health check endpoints for monitoring
``` ```
Claude Desktop (HTTP) → HTTP Wrapper → Gitea MCP Server (stdio) → Gitea API Claude Desktop (HTTP) ──▶ gitea-mcp-remote ──imports──▶ gitea-mcp-server ──API──▶ Gitea
│
├── Authentication (Bearer token)
├── Tool Filtering
└── MCP Streamable HTTP protocol
``` ```
## Features ## Features
@@ -33,27 +37,27 @@ Claude Desktop (HTTP) → HTTP Wrapper → Gitea MCP Server (stdio) → Gitea AP
## Quick Start with Docker ## Quick Start with Docker
The easiest way to deploy is using Docker Compose: The easiest way to deploy is using Docker Compose with Caddy reverse proxy:
```bash ```bash
# 1. Clone the repository # 1. Clone the repository
git clone https://github.com/lmiranda/gitea-mcp-remote.git git clone https://gitea.hotserv.cloud/personal-projects/gitea-mcp-remote.git
cd gitea-mcp-remote cd gitea-mcp-remote
# 2. Create .env file from template # 2. Create .env file from template
cp .env.docker.example .env cp docker/.env.example docker/.env
# 3. Edit .env with your Gitea credentials # 3. Edit .env with your Gitea credentials
nano .env nano docker/.env
# 4. Start the server # 4. Start the services (app + Caddy)
docker-compose up -d docker-compose -f docker/docker-compose.yml up -d
# 5. Check health # 5. Check health
curl http://localhost:8000/health curl http://localhost/health
``` ```
The server will be available at `http://localhost:8000`. The server will be available at `http://localhost` (Caddy) or `http://localhost:8080` (direct).
See [DEPLOYMENT.md](DEPLOYMENT.md) for detailed deployment instructions. See [DEPLOYMENT.md](DEPLOYMENT.md) for detailed deployment instructions.
@@ -96,11 +100,13 @@ The wrapper uses environment variables or a `.env` file for configuration.
GITEA_URL=https://gitea.example.com GITEA_URL=https://gitea.example.com
GITEA_TOKEN=your_gitea_api_token_here GITEA_TOKEN=your_gitea_api_token_here
GITEA_OWNER=your_username_or_org GITEA_OWNER=your_username_or_org
GITEA_REPO=your_repo_name
# HTTP Server # Optional
HTTP_HOST=127.0.0.1 # Use 0.0.0.0 in Docker GITEA_REPO=your_repo_name # Can be omitted, specified per-request
HTTP_PORT=8000
# HTTP Server (defaults)
HTTP_HOST=0.0.0.0
HTTP_PORT=8080
``` ```
### Optional Configuration ### Optional Configuration
@@ -131,6 +137,7 @@ DISABLED_TOOLS=delete_issue,close_milestone # Blacklist mode
#### With Docker #### With Docker
```bash ```bash
cd docker
docker-compose up -d docker-compose up -d
``` ```
@@ -144,19 +151,19 @@ nano .env
# Run the server # Run the server
gitea-mcp-remote gitea-mcp-remote
# Or use the startup script
./scripts/start.sh
``` ```
The server will start on the configured host/port (default: `http://127.0.0.1:8000`). The server will start on the configured host/port (default: `http://0.0.0.0:8080`).
### HTTP Endpoints ### HTTP Endpoints
#### Health Check #### Health Check
```bash ```bash
GET /health GET /health
GET /healthz
GET /ping
Response: {"status": "healthy"} Response: {"status": "ok"}
``` ```
#### MCP Protocol Endpoint #### MCP Protocol Endpoint
@@ -227,7 +234,7 @@ Configure Claude Desktop to use the HTTP wrapper:
{ {
"mcpServers": { "mcpServers": {
"gitea": { "gitea": {
"url": "http://localhost:8000", "url": "http://localhost:8080/mcp",
"headers": { "headers": {
"Authorization": "Bearer YOUR_TOKEN" "Authorization": "Bearer YOUR_TOKEN"
} }
@@ -259,44 +266,49 @@ pip install -e ".[dev]"
```bash ```bash
# Run all tests # Run all tests
pytest pytest tests/ -v
# Run with coverage # Run with coverage
pytest --cov=gitea_mcp_remote pytest tests/ --cov=gitea_mcp_remote
# Run specific test file # Run specific test file
pytest src/gitea_mcp_remote/tests/test_config.py pytest tests/test_mcp_endpoints.py -v
``` ```
### Project Structure ### Project Structure
``` ```
gitea-mcp-remote/ gitea-mcp-remote/
├── src/ ├── src/gitea_mcp_remote/ # Main package
│ └── gitea_mcp_remote/
│ ├── __init__.py │ ├── __init__.py
│ ├── server.py # Main HTTP server │ ├── server_http.py # MCP HTTP server
│ ├── config/ │ ├── config/ # Configuration module
│ │ ├── __init__.py │ │ ├── __init__.py
│ │ └── settings.py # Configuration loader │ │ └── settings.py
│ ├── middleware/ │ ├── middleware/ # HTTP middleware
│ │ ├── __init__.py │ │ ├── __init__.py
│ │ └── auth.py # HTTP authentication │ │ └── auth.py
│ ├── filtering/ │ └── filtering/ # Tool filtering
│ │ ├── __init__.py │ ├── __init__.py
│ │ └── filter.py # Tool filtering │ └── filter.py
│ └── tests/ # Test suite ├── tests/ # Test suite (at repo root)
│ ├── conftest.py │ ├── conftest.py
│ ├── test_config.py │ ├── test_config.py
│ ├── test_filtering.py │ ├── test_filtering.py
│ └── test_middleware.py │ ├── test_middleware.py
├── Dockerfile # Docker image │ └── test_mcp_endpoints.py
├── docker-compose.yml # Docker orchestration ├── docker/ # Docker infrastructure
│ ├── Dockerfile
│ ├── docker-compose.yml
│ ├── Caddyfile
│ └── .env.example
├── scripts/ # Utility scripts
│ ├── start.sh
│ └── healthcheck.sh
├── pyproject.toml # Project config ├── pyproject.toml # Project config
├── requirements.txt # Dependencies ├── requirements.txt # Dependencies
├── .env.example # Config template
├── .env.docker.example # Docker config template
├── README.md # This file ├── README.md # This file
├── CLAUDE.md # Claude Code guidance
└── DEPLOYMENT.md # Deployment guide └── DEPLOYMENT.md # Deployment guide
``` ```
@@ -376,7 +388,7 @@ MIT License - see LICENSE file for details
## Version ## Version
Current version: 0.1.0 Current version: 0.2.0
## Author ## Author
@@ -384,7 +396,7 @@ Leo Miranda
## Links ## Links
- Repository: https://github.com/lmiranda/gitea-mcp-remote - Repository: https://gitea.hotserv.cloud/personal-projects/gitea-mcp-remote
- Issues: https://github.com/lmiranda/gitea-mcp-remote/issues - Issues: https://gitea.hotserv.cloud/personal-projects/gitea-mcp-remote/issues
- Official Gitea MCP Server: https://github.com/modelcontextprotocol/servers/tree/main/src/gitea - Marketplace Package: https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace/src/branch/main/mcp-servers/gitea
- MCP Documentation: https://modelcontextprotocol.io - MCP Documentation: https://modelcontextprotocol.io