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

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