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

- 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>
feat: Add Docker infrastructure with Caddy and startup scripts (#25 , #26 )
2026-02-03 21:32:39 -05:00 · 2026-02-03 21:11:29 -05:00 · 2026-02-03 18:16:51 -05:00 · 2026-02-03 18:16:48 -05:00 · 2026-02-03 18:08:58 -05:00 · 2026-02-03 18:08:54 -05:00
34 changed files with 3596 additions and 483 deletions
--- a/.env.example
+++ b/.env.example
@@ -1,3 +1,7 @@
+# --- Gitea MCP Server env vars (used by marketplace package) ---
+GITEA_API_URL=https://gitea.hotserv.cloud/api/v1
+GITEA_API_TOKEN=your_gitea_personal_access_token
+
 # Gitea Configuration
 GITEA_URL=https://gitea.example.com
 GITEA_TOKEN=your_gitea_api_token_here
@@ -8,6 +12,9 @@ GITEA_REPO=your_repo_name
 HTTP_HOST=127.0.0.1
 HTTP_PORT=8000

+# --- Caddy / TLS ---
+MCP_DOMAIN=mcp-gitea.hotserv.cloud
+
 # Authentication Configuration (Optional)
 # AUTH_TOKEN=your_bearer_token_here

--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -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
--- a/DEPLOYMENT.md
+++ b/DEPLOYMENT.md
@@ -1,6 +1,6 @@
 # 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

@@ -36,15 +36,15 @@ This guide covers production deployment of the Gitea HTTP MCP Wrapper in various
 1. **Clone the repository:**

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

 2. **Create configuration:**

 ```bash
-cp .env.docker.example .env
-nano .env  # Edit with your values
+cp docker/.env.example docker/.env
+nano docker/.env  # Edit with your values
 ```

 Required configuration:
@@ -52,49 +52,49 @@ Required configuration:
 GITEA_URL=https://gitea.example.com
 GITEA_TOKEN=your_gitea_api_token
 GITEA_OWNER=your_username_or_org
-GITEA_REPO=your_default_repo
+GITEA_REPO=your_default_repo  # Optional
 AUTH_TOKEN=your_bearer_token  # Recommended
 ```

-3. **Start the service:**
+3. **Start the services (app + Caddy):**

 ```bash
-docker-compose up -d
+docker-compose -f docker/docker-compose.yml up -d
 ```

 4. **Verify deployment:**

 ```bash
-curl http://localhost:8000/health
+curl http://localhost/health      # Via Caddy
+curl http://localhost:8080/health # Direct to app
 ```

 ### 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
-version: '3.8'
-
 services:
-  gitea-mcp-wrapper:
+  # Python MCP Server
+  app:
    build:
-      context: .
-      dockerfile: Dockerfile
-    image: gitea-mcp-wrapper:latest
-    container_name: gitea-mcp-wrapper
+      context: ..
+      dockerfile: docker/Dockerfile
+    image: gitea-mcp-remote:latest
+    container_name: gitea-mcp-remote-app
    restart: always
-    ports:
-      - "127.0.0.1:8000:8000"  # Bind to localhost only
+    expose:
+      - "8080"
    environment:
      - GITEA_URL=${GITEA_URL}
      - GITEA_TOKEN=${GITEA_TOKEN}
      - GITEA_OWNER=${GITEA_OWNER}
-      - GITEA_REPO=${GITEA_REPO}
+      - GITEA_REPO=${GITEA_REPO:-}
      - HTTP_HOST=0.0.0.0
-      - HTTP_PORT=8000
-      - AUTH_TOKEN=${AUTH_TOKEN}
+      - HTTP_PORT=8080
+      - AUTH_TOKEN=${AUTH_TOKEN:-}
    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
      timeout: 3s
      retries: 3
@@ -107,9 +107,31 @@ services:
    networks:
      - 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:
  gitea-mcp-network:
    driver: bridge
+
+volumes:
+  caddy_data:
+  caddy_config:
 ```

 ### Docker Build Options
@@ -117,20 +139,20 @@ networks:
 **Build the image:**

 ```bash
-docker build -t gitea-mcp-wrapper:latest .
+docker build -f docker/Dockerfile -t gitea-mcp-remote:latest .
 ```

 **Build with specific Python version:**

 ```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:**

 ```bash
-docker tag gitea-mcp-wrapper:latest registry.example.com/gitea-mcp-wrapper:latest
-docker push 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-remote:latest
 ```

 ## Security Best Practices
@@ -218,7 +240,7 @@ Docker automatically monitors the health check and can restart if unhealthy:

 ```yaml
 healthcheck:
-  test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
+  test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
  interval: 30s
  timeout: 3s
  retries: 3
--- a/README.md
+++ b/README.md
@@ -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
 ```

@@ -143,46 +150,71 @@ cp .env.example .env
 nano .env

 # Run the server
-gitea-http-wrapper
+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"}
 ```

-#### List Tools
-```bash
-POST /tools/list
+#### MCP Protocol Endpoint

-Response: {
-  "tools": [
-    {"name": "list_issues", "description": "...", "inputSchema": {...}},
-    ...
-  ]
-}
-```
+The server implements the MCP Streamable HTTP protocol:

-#### Call Tool
 ```bash
-POST /tools/call
+# Check protocol version
+HEAD /mcp
+
+# Send MCP JSON-RPC requests
+POST /mcp
 Content-Type: application/json
+Accept: application/json, text/event-stream
 Authorization: Bearer YOUR_TOKEN  # If auth enabled

+# Example: Initialize
 {
-  "name": "list_issues",
-  "arguments": {
-    "owner": "myorg",
-    "repo": "myrepo",
-    "state": "open"
+  "jsonrpc": "2.0",
+  "id": 1,
+  "method": "initialize",
+  "params": {
+    "protocolVersion": "2024-11-05",
+    "capabilities": {},
+    "clientInfo": {
+      "name": "my-client",
+      "version": "1.0.0"
+    }
+  }
+}
+
+# Example: List tools
+{
+  "jsonrpc": "2.0",
+  "id": 2,
+  "method": "tools/list",
+  "params": {}
+}
+
+# Example: Call tool
+{
+  "jsonrpc": "2.0",
+  "id": 3,
+  "method": "tools/call",
+  "params": {
+    "name": "list_issues",
+    "arguments": {
+      "owner": "myorg",
+      "repo": "myrepo",
+      "state": "open"
+    }
  }
 }
 ```
@@ -202,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"
      }
@@ -234,44 +266,49 @@ pip install -e ".[dev]"

 ```bash
 # Run all tests
-pytest
+pytest tests/ -v

 # Run with coverage
-pytest --cov=gitea_http_wrapper
+pytest tests/ --cov=gitea_mcp_remote

 # Run specific test file
-pytest src/gitea_http_wrapper/tests/test_config.py
+pytest tests/test_mcp_endpoints.py -v
 ```

 ### Project Structure

 ```
 gitea-mcp-remote/
-├── src/
-│   └── gitea_http_wrapper/
+├── 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
 ```

@@ -330,7 +367,7 @@ If tool filtering is not applied:
 1. Check `.env` file syntax (no spaces around `=`)
 2. Verify comma-separated list format
 3. Check server logs for filter configuration
-4. Query `POST /tools/list` to see filtered tools
+4. Send `tools/list` MCP request to see filtered tools

 ## Security Considerations

@@ -351,7 +388,7 @@ MIT License - see LICENSE file for details

 ## Version

-Current version: 0.1.0
+Current version: 0.2.0

 ## Author

@@ -359,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
--- a/docker/.env.example
+++ b/docker/.env.example
@@ -0,0 +1,38 @@
+# Gitea MCP Remote - Docker Environment Configuration
+#
+# Copy this file to .env and fill in your values:
+#   cp .env.example .env
+
+# =============================================================================
+# Required Configuration
+# =============================================================================
+
+# Gitea instance URL (e.g., https://gitea.example.com)
+GITEA_URL=https://gitea.example.com
+
+# Gitea API token for authentication
+# Generate at: Settings -> Applications -> Generate New Token
+GITEA_TOKEN=your_gitea_api_token_here
+
+# Default repository owner/organization
+GITEA_OWNER=your_username_or_org
+
+# =============================================================================
+# Optional Configuration
+# =============================================================================
+
+# Default repository name (optional - can be specified per-request)
+GITEA_REPO=
+
+# Bearer token for MCP endpoint authentication (optional)
+# If set, clients must include "Authorization: Bearer <token>" header
+AUTH_TOKEN=
+
+# MCP authentication mode: 'required', 'optional', or 'none'
+MCP_AUTH_MODE=optional
+
+# Tool filtering (optional, comma-separated)
+# ENABLED_TOOLS=list_issues,create_issue,list_labels
+# DISABLED_TOOLS=delete_issue,delete_label
+ENABLED_TOOLS=
+DISABLED_TOOLS=
--- a/docker/Caddyfile
+++ b/docker/Caddyfile
@@ -0,0 +1,46 @@
+# Caddy reverse proxy configuration for Gitea MCP Remote
+#
+# This configuration provides:
+# - HTTPS termination with automatic certificates
+# - Reverse proxy to the Python MCP server
+# - Health check endpoint passthrough
+# - MCP protocol endpoint routing
+{
+    # Global options
+    email admin@example.com
+
+    # For local development, disable HTTPS redirect
+    # auto_https off
+}
+
+# Default site - adjust domain as needed
+:443, :80 {
+    # Health check endpoint - no authentication
+    handle /health {
+        reverse_proxy app:8080
+    }
+
+    # MCP protocol endpoint
+    handle /mcp {
+        reverse_proxy app:8080 {
+            # Pass through headers for MCP protocol
+            header_up X-Forwarded-Proto {scheme}
+            header_up X-Real-IP {remote_host}
+
+            # Ensure proper content type handling
+            flush_interval -1
+        }
+    }
+
+    # Fallback - proxy all other requests
+    handle {
+        reverse_proxy app:8080
+    }
+
+    # Logging
+    log {
+        output stdout
+        format console
+    }
+}
+}
--- a/docker/Dockerfile
+++ b/docker/Dockerfile
@@ -0,0 +1,65 @@
+# Gitea MCP Remote — Dockerfile
+# Multi-stage build for optimized image size
+
+FROM python:3.11-slim as builder
+
+# Set working directory
+WORKDIR /build
+
+# Install build dependencies including git for marketplace dependency
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends \
+    gcc \
+    git \
+    && rm -rf /var/lib/apt/lists/*
+
+# Copy requirements first for better caching
+COPY requirements.txt .
+RUN pip install --user --no-cache-dir -r requirements.txt
+
+# Copy source code
+COPY pyproject.toml .
+COPY src/ src/
+
+# Install package (includes marketplace dependency from git)
+RUN pip install --user --no-cache-dir .
+
+# Production stage
+FROM python:3.11-slim
+
+# Install runtime dependencies
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends \
+    curl \
+    && rm -rf /var/lib/apt/lists/*
+
+# Set working directory
+WORKDIR /app
+
+# Copy installed packages from builder
+COPY --from=builder /root/.local /root/.local
+
+# Copy source code
+COPY src/ src/
+COPY pyproject.toml .
+
+# Make sure scripts in .local are usable
+ENV PATH=/root/.local/bin:$PATH
+
+# Set Python environment variables
+ENV PYTHONUNBUFFERED=1
+ENV PYTHONDONTWRITEBYTECODE=1
+
+# Default to port 8080 (Caddy proxies to this)
+ENV HTTP_PORT=8080
+ENV HTTP_HOST=0.0.0.0
+
+# Expose port
+EXPOSE 8080
+
+# Health check using curl
+HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
+    CMD curl -f http://localhost:8080/health || exit 1
+
+# Run the MCP server
+CMD ["gitea-mcp-remote"]
--- a/docker/docker-compose.yml
+++ b/docker/docker-compose.yml
@@ -0,0 +1,66 @@
+services:
+  # Python MCP Server
+  app:
+    build:
+      context: ..
+      dockerfile: docker/Dockerfile
+    image: gitea-mcp-remote:latest
+    container_name: gitea-mcp-remote-app
+    restart: unless-stopped
+    expose:
+      - "8080"
+    environment:
+      # Gitea Configuration (required)
+      - GITEA_URL=${GITEA_URL}
+      - GITEA_TOKEN=${GITEA_TOKEN}
+      - GITEA_OWNER=${GITEA_OWNER}
+      # Optional Gitea config
+      - GITEA_REPO=${GITEA_REPO:-}
+
+      # HTTP Server Configuration
+      - HTTP_HOST=0.0.0.0
+      - HTTP_PORT=8080
+
+      # Authentication (optional - for MCP endpoint)
+      - AUTH_TOKEN=${AUTH_TOKEN:-}
+      - MCP_AUTH_MODE=${MCP_AUTH_MODE:-optional}
+
+      # Tool Filtering (optional)
+      - ENABLED_TOOLS=${ENABLED_TOOLS:-}
+      - DISABLED_TOOLS=${DISABLED_TOOLS:-}
+
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
+      interval: 30s
+      timeout: 3s
+      retries: 3
+      start_period: 5s
+
+    networks:
+      - gitea-mcp-network
+
+  # Caddy Reverse Proxy
+  caddy:
+    image: caddy:2-alpine
+    container_name: gitea-mcp-remote-caddy
+    restart: unless-stopped
+    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:
+  gitea-mcp-network:
+    driver: bridge
+
+volumes:
+  caddy_data:
+  caddy_config:
--- a/docs/sprint-proposals/SPRINT-01-SUMMARY.md
+++ b/docs/sprint-proposals/SPRINT-01-SUMMARY.md
@@ -0,0 +1,244 @@
+# Sprint 01: Core Architecture Correction - SUMMARY
+
+**Status:** 🟡 AWAITING APPROVAL
+**Milestone:** [Sprint 01: Core Architecture Correction](https://gitea.hotserv.cloud/personal-projects/gitea-mcp-remote/milestone/29)
+**Sprint Duration:** 1 week (Feb 3-10, 2026)
+**Total Estimated Effort:** 19-28 hours
+
+---
+
+## Sprint Overview
+
+This sprint addresses **three fatal architectural problems** introduced in the v1.0.0 release. This is **surgical correction work**, not a rewrite - supporting modules (config, middleware, filtering, tests) are solid and only need import path updates.
+
+### The Three Fatal Problems
+
+1. **Subprocess Architecture → Direct Python Import**
+   - Current: Spawns gitea-mcp-server as subprocess
+   - Required: Direct Python import from marketplace package
+
+2. **Custom REST API → MCP Streamable HTTP Protocol**
+   - Current: Custom endpoints `/tools/list` and `/tools/call`
+   - Required: MCP protocol `POST /mcp` with JSON-RPC 2.0
+
+3. **Missing Marketplace Dependency**
+   - Current: Comment about installing separately
+   - Required: Actual pip dependency from marketplace Git repo
+
+---
+
+## Issues Created
+
+All issues are in Gitea milestone: **Sprint 01: Core Architecture Correction**
+
+| Issue | Title | Type | Size | Est. Time | Dependencies |
+|-------|-------|------|------|-----------|--------------|
+| [#19](https://gitea.hotserv.cloud/personal-projects/gitea-mcp-remote/issues/19) | Rename package to gitea_mcp_remote and update configuration | Refactor | M | 2-3h | None |
+| [#20](https://gitea.hotserv.cloud/personal-projects/gitea-mcp-remote/issues/20) | Update middleware and filtering with new import paths | Refactor | S | 1h | #19 |
+| [#21](https://gitea.hotserv.cloud/personal-projects/gitea-mcp-remote/issues/21) | Move tests to repository root and update imports | Refactor | M | 1-2h | #19, #20 |
+| [#22](https://gitea.hotserv.cloud/personal-projects/gitea-mcp-remote/issues/22) | Add marketplace dependency and update project config | Build | S | 1h | #19 |
+| [#23](https://gitea.hotserv.cloud/personal-projects/gitea-mcp-remote/issues/23) | Remove old server and create MCP base server structure | Feature | M | 2-3h | #19, #20, #22 |
+| [#24](https://gitea.hotserv.cloud/personal-projects/gitea-mcp-remote/issues/24) | Implement MCP Streamable HTTP protocol endpoints | Feature | M | 2-3h | #23 |
+| [#25](https://gitea.hotserv.cloud/personal-projects/gitea-mcp-remote/issues/25) | Create Docker multi-service infrastructure with Caddy | Build | M | 3-4h | #22, #24 |
+| [#26](https://gitea.hotserv.cloud/personal-projects/gitea-mcp-remote/issues/26) | Create startup scripts and MCP server tests | Test | M | 2-3h | #24 |
+| [#27](https://gitea.hotserv.cloud/personal-projects/gitea-mcp-remote/issues/27) | Create CLAUDE.md and update deployment documentation | Docs | M | 2-3h | All |
+| [#28](https://gitea.hotserv.cloud/personal-projects/gitea-mcp-remote/issues/28) | Final validation and integration testing | Test | M | 2-3h | All |
+
+**Total Issues:** 10 (was 9, split large task into 2 medium tasks)
+
+---
+
+## Execution Order
+
+The dependency graph ensures proper execution order:
+
+```
+#19 (Rename + Config) ← FOUNDATION
+  ├─→ #20 (Middleware + Filtering)
+  │     └─→ #21 (Tests)
+  │
+  ├─→ #22 (pyproject.toml)
+  │     ├─→ #23 (MCP Base Server)
+  │     │     ├─→ #24 (MCP Protocol)
+  │     │     │     ├─→ #25 (Docker)
+  │     │     │     └─→ #26 (Scripts + Tests)
+  │     │     │
+  │     └─→ #21 (Tests - can run parallel)
+  │
+  └─→ All above
+        └─→ #27 (Documentation)
+              └─→ #28 (Final Validation)
+```
+
+**Recommended sequence:**
+1. #19 → #20 → #22 → #21 (Foundation - Day 1-2)
+2. #23 → #24 (Core server - Day 2-3)
+3. #25 → #26 (Infrastructure - Day 3-4)
+4. #27 → #28 (Documentation and validation - Day 4-5)
+
+---
+
+## What to KEEP (Rename Imports Only)
+
+These modules are **well-tested and solid**:
+
+- ✅ `config/settings.py` - Minor field changes only
+- ✅ `middleware/auth.py` - Import paths only
+- ✅ `filtering/filter.py` - Change ValueError to warning
+- ✅ All tests - Move to root, update imports
+- ✅ `DEPLOYMENT.md` - Update references
+
+---
+
+## What to REPLACE
+
+- ❌ `server.py` → ✅ `server_http.py` (new MCP implementation)
+- ❌ `pyproject.toml` → ✅ Updated with marketplace dependency
+- ❌ `docker-compose.yml` → ✅ `docker/docker-compose.yml` (two services)
+- ❌ `Dockerfile` → ✅ `docker/Dockerfile` (git + port 8080)
+
+---
+
+## New Files to CREATE
+
+- 📄 `docker/Caddyfile` - Reverse proxy config
+- 📄 `CLAUDE.md` - Project guidance for Claude Code
+- 📄 `tests/test_server_http.py` - MCP server tests
+- 📄 `scripts/start.sh` - Production startup
+- 📄 `scripts/healthcheck.sh` - Docker healthcheck
+
+---
+
+## Success Criteria (16 Validations)
+
+### Package Structure (3)
+- [ ] `src/gitea_mcp_remote/` exists (not `gitea_http_wrapper`)
+- [ ] No imports reference `gitea_http_wrapper`
+- [ ] `tests/` is at repository root (not in `src/`)
+
+### Configuration (3)
+- [ ] `config/settings.py` has `mcp_auth_mode` field
+- [ ] `config/settings.py` has `gitea_repo: str | None`
+- [ ] HTTP defaults are `0.0.0.0:8080`
+
+### Server Implementation (4)
+- [ ] `server_http.py` imports from `mcp_server` package
+- [ ] MCP endpoints exist: `POST /mcp`, `HEAD /mcp`
+- [ ] Health endpoints exist: `/health`, `/healthz`, `/ping`
+- [ ] No subprocess spawning code
+
+### Dependencies (3)
+- [ ] `pyproject.toml` has marketplace Git dependency
+- [ ] Entry point is `gitea-mcp-remote` (not `gitea-http-wrapper`)
+- [ ] Can run: `pip install -e .` successfully
+
+### Docker (3)
+- [ ] `docker/docker-compose.yml` has two services (app + caddy)
+- [ ] `docker/Dockerfile` installs git and uses port 8080
+- [ ] `docker/Caddyfile` exists and proxies to app:8080
+
+---
+
+## Timeline
+
+### Effort Distribution
+- **Small (1-2h):** 2 issues (#20, #22) = 2-4 hours
+- **Medium (2-4h):** 8 issues (#19, #21, #23-28) = 17-24 hours
+- **Total:** 19-28 hours ≈ 23.5 hours average
+
+### Sprint Schedule (1 week)
+- **Day 1-2:** Foundation (Issues #19-22) - 5-7 hours
+- **Day 2-3:** Core Server (Issues #23-24) - 4-6 hours
+- **Day 3-4:** Infrastructure (Issues #25-26) - 5-7 hours
+- **Day 4-5:** Docs & Validation (Issues #27-28) - 4-6 hours
+- **Buffer:** 1-2 hours for unexpected issues
+
+---
+
+## Risk Assessment
+
+### Low Risk ✅
+- Config, middleware, filtering: Well-tested, only import changes
+- Test relocation: No logic changes
+
+### Medium Risk ⚠️
+- `server_http.py`: New file, but following MCP HTTP spec
+- MCP protocol integration: Well-documented standard
+
+### High Risk 🔴
+- Docker multi-service: Requires Caddy configuration
+- Marketplace Git dependency: Must be accessible during build
+
+### Mitigation
+1. Execute in exact dependency order
+2. Test at each major milestone
+3. Validate Docker build before deployment
+4. Keep development branch for rollback
+
+---
+
+## Documentation Created
+
+1. **[sprint-01-core-architecture-correction.md](./sprint-01-core-architecture-correction.md)**
+   - Executive summary
+   - Three fatal problems explained
+   - What to keep vs replace
+   - Architecture diagram
+   - Risk assessment
+
+2. **[sprint-01-implementation-guide.md](./sprint-01-implementation-guide.md)**
+   - Step-by-step technical implementation
+   - Code snippets for each change
+   - Validation commands
+   - Complete file replacements
+
+3. **[sprint-01-issue-breakdown.md](./sprint-01-issue-breakdown.md)**
+   - Detailed issue descriptions
+   - Dependency graph
+   - Execution order
+   - Size distribution
+
+4. **[SPRINT-01-SUMMARY.md](./SPRINT-01-SUMMARY.md)** (this file)
+   - Sprint overview
+   - Issue table with links
+   - Success criteria
+   - Approval checklist
+
+---
+
+## Links
+
+- **Milestone:** https://gitea.hotserv.cloud/personal-projects/gitea-mcp-remote/milestone/29
+- **Repository:** https://gitea.hotserv.cloud/personal-projects/gitea-mcp-remote
+- **Branch:** development
+- **Marketplace:** https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace
+
+---
+
+## Approval Checklist
+
+Before execution begins, verify:
+
+- [ ] All 10 issues created and assigned to milestone
+- [ ] Dependencies correctly set between issues
+- [ ] Labels applied correctly (Type, Priority, Component, Size)
+- [ ] Implementation guide reviewed and accurate
+- [ ] Timeline is realistic (1 week)
+- [ ] Success criteria are clear and testable
+- [ ] Rollback plan understood (development branch)
+- [ ] User has reviewed and approved the plan
+
+---
+
+## Next Steps
+
+**AWAITING USER APPROVAL** to begin execution.
+
+Once approved:
+1. Start with Issue #19 (Foundation)
+2. Follow dependency order strictly
+3. Update issue status as work progresses
+4. Run validation after each major milestone
+5. Complete sprint with Issue #28 (Final Validation)
+
+**Note:** This is attempt #3. User emphasized paying close attention to details. All requirements from the architectural correction prompt have been captured in the issue breakdown.
--- a/docs/sprint-proposals/sprint-01-core-architecture-correction.md
+++ b/docs/sprint-proposals/sprint-01-core-architecture-correction.md
@@ -0,0 +1,329 @@
+# Sprint 01: Core Architecture Correction
+
+**Status:** Planning
+**Sprint Duration:** 1 week (estimated 20-24 hours of work)
+**Priority:** CRITICAL - Architectural Foundation
+**Attempt:** #3 (Pay close attention to details)
+
+## Executive Summary
+
+This sprint addresses three fatal architectural problems introduced in the v1.0.0 release that prevent the HTTP wrapper from functioning correctly with the MCP protocol. This is **surgical correction work**, not a rewrite. Supporting modules (config, middleware, filtering, tests) are solid and only need import path updates.
+
+## The Three Fatal Problems
+
+### 1. Subprocess Architecture → Direct Python Import
+**Current (Wrong):** `server.py` spawns `gitea-mcp-server` as a subprocess
+**Required (Correct):** Direct Python import from marketplace package
+
+```python
+# WRONG (current)
+self.process = await asyncio.create_subprocess_exec("gitea-mcp-server", ...)
+
+# CORRECT (target)
+from mcp_server import get_tool_definitions, create_tool_dispatcher, GiteaClient, GiteaConfig
+```
+
+**Why this is fatal:** Cannot access marketplace code as subprocess, breaks MCP protocol contract.
+
+### 2. Custom REST API → MCP Streamable HTTP Protocol
+**Current (Wrong):** Custom endpoints `/tools/list` and `/tools/call`
+**Required (Correct):** MCP Streamable HTTP protocol
+
+```python
+# WRONG (current)
+POST /tools/list
+POST /tools/call
+
+# CORRECT (target)
+POST /mcp          # JSON-RPC 2.0 messages
+HEAD /mcp          # Protocol version header
+```
+
+**Why this is fatal:** Not compatible with Claude Desktop's MCP client implementation.
+
+### 3. Missing Marketplace Dependency
+**Current (Wrong):** Comment in pyproject.toml about installing separately
+**Required (Correct):** Actual pip dependency from marketplace Git repository
+
+```toml
+# WRONG (current)
+# gitea-mcp-server - installed separately (not on PyPI yet)
+
+# CORRECT (target)
+dependencies = [
+    "gitea-mcp-server @ git+https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace.git#subdirectory=mcp-servers/gitea",
+    ...
+]
+```
+
+**Why this is fatal:** Dependency not installable, breaks Docker builds and deployment.
+
+## What to KEEP (Rename Imports Only)
+
+These modules are **solid and well-tested**. Only update import paths from `gitea_http_wrapper` to `gitea_mcp_remote`:
+
+### config/settings.py
+- **Keep:** Overall structure, Pydantic settings, validation logic
+- **Minor changes:**
+  - Make `gitea_repo` optional (allow None)
+  - Add `mcp_auth_mode: str = "optional"` field
+  - Change HTTP defaults: `http_host="0.0.0.0"`, `http_port=8080`
+  - Remove `get_gitea_mcp_env()` method (no longer needed for subprocess)
+
+### middleware/auth.py
+- **Keep:** Entire file logic unchanged
+- **Change:** Import paths only (`gitea_http_wrapper` → `gitea_mcp_remote`)
+
+### filtering/filter.py
+- **Keep:** Entire filtering logic
+- **Changes:**
+  - Line 30: Change `raise ValueError(...)` to `logger.warning(...)` (non-fatal)
+  - Import paths: `gitea_http_wrapper` → `gitea_mcp_remote`
+
+### Tests (all files)
+- **Keep:** All test logic and fixtures
+- **Move:** `src/gitea_http_wrapper/tests/` → `tests/` (top-level)
+- **Change:** Import paths to reflect new structure
+
+### DEPLOYMENT.md
+- **Keep:** Overall deployment guide structure
+- **Update:** References to new MCP endpoints, Docker structure, marketplace dependency
+
+## What to REPLACE
+
+### server.py → server_http.py
+**Complete replacement** with:
+- Direct Python imports from marketplace `mcp_server`
+- MCP Streamable HTTP transport (`POST /mcp`, `HEAD /mcp`)
+- JSON-RPC 2.0 message handling
+- GiteaClient instantiation with GiteaConfig
+- Tool dispatcher integration
+- Keep health endpoints: `/health`, `/healthz`, `/ping`
+
+### pyproject.toml
+**Full replacement** with:
+- Marketplace Git dependency
+- Updated package name: `gitea-mcp-remote`
+- New entry point: `gitea-mcp-remote = "gitea_mcp_remote.server_http:main"`
+- Updated test paths: `testpaths = ["tests"]`
+
+### docker-compose.yml → docker/docker-compose.yml
+**Move and restructure** with:
+- Two services: `app` (Python server) and `caddy` (reverse proxy)
+- App listens on port 8080 (internal)
+- Caddy exposes port 443 (external HTTPS)
+- Volume for Caddy certs persistence
+
+### Dockerfile → docker/Dockerfile
+**Replace** with:
+- Install `git` package (for Git dependency install)
+- Expose port 8080 (not 8000)
+- Use `curl` for healthcheck (not wget)
+- Install from `requirements.txt` first, then marketplace dependency
+
+## New Files to CREATE
+
+### docker/Caddyfile
+Reverse proxy configuration:
+- HTTPS termination
+- Proxy to app:8080
+- MCP endpoint routing
+
+### CLAUDE.md
+Project guidance for Claude Code:
+- Architecture explanation
+- Development workflows
+- Deployment procedures
+- MCP protocol notes
+
+### scripts/start.sh
+Production startup script:
+- Environment validation
+- Graceful startup
+- Logging configuration
+
+### scripts/healthcheck.sh
+Docker healthcheck script:
+- Check `/health` endpoint
+- Validate MCP endpoint
+- Exit codes for Docker
+
+### tests/test_server_http.py
+New test file for HTTP server:
+- MCP endpoint tests
+- JSON-RPC 2.0 validation
+- Protocol version tests
+
+## Package Rename
+
+**From:** `src/gitea_http_wrapper/`
+**To:** `src/gitea_mcp_remote/`
+
+All imports throughout codebase must be updated:
+```python
+# OLD
+from gitea_http_wrapper.config import GiteaSettings
+
+# NEW
+from gitea_mcp_remote.config import GiteaSettings
+```
+
+## Execution Order (18 Steps)
+
+This is the **exact sequence** that must be followed:
+
+1. Rename package directory: `gitea_http_wrapper` → `gitea_mcp_remote`
+2. Update `config/settings.py` (fields + imports)
+3. Update `middleware/auth.py` (imports only)
+4. Update `filtering/filter.py` (warning + imports)
+5. Move tests: `src/gitea_mcp_remote/tests/` → `tests/`
+6. Update all test imports
+7. Delete old `server.py`
+8. Create new `server_http.py` with MCP protocol
+9. Replace `pyproject.toml` with marketplace dependency
+10. Update `pytest.ini` test paths
+11. Create `docker/` directory
+12. Move and update `docker-compose.yml` → `docker/docker-compose.yml`
+13. Replace `Dockerfile` → `docker/Dockerfile`
+14. Create `docker/Caddyfile`
+15. Create `scripts/start.sh` and `scripts/healthcheck.sh`
+16. Create `tests/test_server_http.py`
+17. Create `CLAUDE.md`
+18. Update `DEPLOYMENT.md` references
+
+## Validation Checklist (16 Items)
+
+After implementation, ALL must pass:
+
+### Package Structure
+- [ ] `src/gitea_mcp_remote/` exists (not `gitea_http_wrapper`)
+- [ ] No imports reference `gitea_http_wrapper`
+- [ ] `tests/` is at repository root (not in `src/`)
+
+### Configuration
+- [ ] `config/settings.py` has `mcp_auth_mode` field
+- [ ] `config/settings.py` has `gitea_repo: str | None`
+- [ ] HTTP defaults are `0.0.0.0:8080`
+
+### Server Implementation
+- [ ] `server_http.py` imports from `mcp_server` package
+- [ ] MCP endpoints exist: `POST /mcp`, `HEAD /mcp`
+- [ ] Health endpoints exist: `/health`, `/healthz`, `/ping`
+- [ ] No subprocess spawning code
+
+### Dependencies
+- [ ] `pyproject.toml` has marketplace Git dependency
+- [ ] Entry point is `gitea-mcp-remote` (not `gitea-http-wrapper`)
+- [ ] Can run: `pip install -e .` successfully
+
+### Docker
+- [ ] `docker/docker-compose.yml` has two services (app + caddy)
+- [ ] `docker/Dockerfile` installs git and uses port 8080
+- [ ] `docker/Caddyfile` exists and proxies to app:8080
+
+### Tests
+- [ ] All tests pass: `pytest tests/`
+
+## Architecture Diagram
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ Claude Desktop (MCP Client)                                 │
+└───────────────────────┬─────────────────────────────────────┘
+                        │ JSON-RPC 2.0 over HTTP
+                        │ POST /mcp
+                        ↓
+┌─────────────────────────────────────────────────────────────┐
+│ Caddy (HTTPS Termination)                                   │
+│ - TLS/SSL                                                   │
+│ - Reverse proxy to :8080                                    │
+└───────────────────────┬─────────────────────────────────────┘
+                        │
+                        ↓
+┌─────────────────────────────────────────────────────────────┐
+│ server_http.py (MCP HTTP Transport)                         │
+│ ┌─────────────────────────────────────────────────────────┐ │
+│ │ Starlette App                                           │ │
+│ │ - POST /mcp (JSON-RPC handler)                          │ │
+│ │ - HEAD /mcp (protocol version)                          │ │
+│ │ - /health endpoints                                     │ │
+│ └────────────────────┬────────────────────────────────────┘ │
+│                      │                                       │
+│                      ↓                                       │
+│ ┌─────────────────────────────────────────────────────────┐ │
+│ │ Middleware Stack                                        │ │
+│ │ - BearerAuthMiddleware (auth.py) ✓ Keep                │ │
+│ │ - HealthCheckBypassMiddleware     ✓ Keep                │ │
+│ └────────────────────┬────────────────────────────────────┘ │
+│                      │                                       │
+│                      ↓                                       │
+│ ┌─────────────────────────────────────────────────────────┐ │
+│ │ Tool Dispatcher                                         │ │
+│ │ - create_tool_dispatcher() from mcp_server             │ │
+│ │ - Tool filtering (filter.py) ✓ Keep                    │ │
+│ └────────────────────┬────────────────────────────────────┘ │
+└──────────────────────┼──────────────────────────────────────┘
+                       │ Direct Python calls
+                       ↓
+┌─────────────────────────────────────────────────────────────┐
+│ Marketplace: mcp_server (gitea-mcp-server)                  │
+│ - GiteaClient                                               │
+│ - GiteaConfig                                               │
+│ - get_tool_definitions()                                    │
+│ - create_tool_dispatcher()                                  │
+└───────────────────────┬─────────────────────────────────────┘
+                        │ HTTPS API calls
+                        ↓
+┌─────────────────────────────────────────────────────────────┐
+│ Gitea Instance (gitea.hotserv.cloud)                        │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Risk Assessment
+
+### Low Risk (Supporting Modules)
+- Config, middleware, filtering: Well-tested, only import changes
+- Tests: Moving location, no logic changes
+
+### Medium Risk (New Server Implementation)
+- `server_http.py`: New file, but following MCP HTTP spec closely
+- MCP protocol integration: Well-documented standard
+
+### High Risk (Deployment Changes)
+- Docker multi-service setup: Requires Caddy configuration
+- Marketplace Git dependency: Must be accessible during build
+
+### Mitigation Strategy
+1. Execute in exact order (dependencies first, server last)
+2. Test at each major milestone (config → middleware → server)
+3. Validate Docker build before final deployment
+4. Keep development branch for rollback if needed
+
+## Success Criteria
+
+1. ✅ All 16 validation items pass
+2. ✅ Can install via `pip install -e .`
+3. ✅ Can build Docker image successfully
+4. ✅ Can start via `docker-compose up`
+5. ✅ MCP endpoint responds to `POST /mcp` with protocol version
+6. ✅ Claude Desktop can connect and list tools
+7. ✅ Can create Gitea issue via MCP protocol
+8. ✅ All tests pass
+
+## Timeline Estimate
+
+- **Setup & Config Changes:** 2-3 hours
+- **Server Rewrite:** 4-6 hours
+- **Docker Restructure:** 3-4 hours
+- **Testing & Validation:** 4-5 hours
+- **Documentation:** 2-3 hours
+- **Buffer for Issues:** 4-5 hours
+
+**Total:** 19-26 hours → 1 week sprint
+
+## References
+
+- MCP Streamable HTTP Spec: https://spec.modelcontextprotocol.io/specification/basic/transports/
+- JSON-RPC 2.0 Spec: https://www.jsonrpc.org/specification
+- Marketplace Repository: https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace
+- Original Issue: (To be created in this sprint)
--- a/docs/sprint-proposals/sprint-01-implementation-guide.md
+++ b/docs/sprint-proposals/sprint-01-implementation-guide.md
--- a/docs/sprint-proposals/sprint-01-issue-breakdown.md
+++ b/docs/sprint-proposals/sprint-01-issue-breakdown.md
@@ -0,0 +1,489 @@
+# Sprint 01: Issue Breakdown
+
+## Issue Structure
+
+Each issue is sized for 1-4 hours of work and includes:
+- Clear acceptance criteria
+- Dependencies on other issues
+- Reference to implementation guide
+- Appropriate labels
+
+---
+
+## Issue #1: Rename Package Directory and Update Config
+
+**Title:** `[Sprint 01] refactor: Rename package to gitea_mcp_remote and update configuration`
+
+**Estimated Time:** 2-3 hours
+
+**Labels:**
+- `Type/Refactor`
+- `Priority/High`
+- `Component/Core`
+- `Size/M`
+
+**Dependencies:** None
+
+**Description:**
+
+Rename the package directory from `gitea_http_wrapper` to `gitea_mcp_remote` and update the configuration module with new fields required for MCP protocol.
+
+**Tasks:**
+- [ ] Rename `src/gitea_http_wrapper/` to `src/gitea_mcp_remote/`
+- [ ] Update `config/settings.py`:
+  - Make `gitea_repo` optional (allow None)
+  - Add `mcp_auth_mode: str = "optional"` field
+  - Change HTTP defaults: `http_host="0.0.0.0"`, `http_port=8080`
+  - Remove `get_gitea_mcp_env()` method
+- [ ] Update `config/__init__.py` imports
+- [ ] Verify imports work: `from gitea_mcp_remote.config import GiteaSettings`
+
+**Acceptance Criteria:**
+- Package directory is `src/gitea_mcp_remote/`
+- Config has `mcp_auth_mode` field
+- Config has optional `gitea_repo` field
+- HTTP defaults are `0.0.0.0:8080`
+- Can import: `from gitea_mcp_remote.config import GiteaSettings`
+
+**Implementation Reference:**
+See `docs/sprint-proposals/sprint-01-implementation-guide.md` - Phase 1, Issues #1-2
+
+---
+
+## Issue #2: Update Middleware and Filtering Modules
+
+**Title:** `[Sprint 01] refactor: Update middleware and filtering with new import paths`
+
+**Estimated Time:** 1 hour
+
+**Labels:**
+- `Type/Refactor`
+- `Priority/High`
+- `Component/Core`
+- `Size/S`
+
+**Dependencies:** Issue #1
+
+**Description:**
+
+Update middleware and filtering modules to use new package name. Middleware requires only import changes, filtering changes ValueError to warning.
+
+**Tasks:**
+- [ ] Update `middleware/__init__.py` imports
+- [ ] Update `middleware/auth.py` - imports only
+- [ ] Update `filtering/__init__.py` imports
+- [ ] Update `filtering/filter.py`:
+  - Add logging import
+  - Change line 29-32 ValueError to logger.warning
+- [ ] Verify imports work
+
+**Acceptance Criteria:**
+- Middleware imports from `gitea_mcp_remote.middleware`
+- Filtering imports from `gitea_mcp_remote.filtering`
+- ToolFilter logs warning instead of raising ValueError when both filter types specified
+- Can import both modules successfully
+
+**Implementation Reference:**
+See `docs/sprint-proposals/sprint-01-implementation-guide.md` - Phase 2, Issues #3-4
+
+---
+
+## Issue #3: Relocate Tests and Update Imports
+
+**Title:** `[Sprint 01] refactor: Move tests to repository root and update imports`
+
+**Estimated Time:** 1-2 hours
+
+**Labels:**
+- `Type/Refactor`
+- `Priority/High`
+- `Component/Tests`
+- `Size/M`
+
+**Dependencies:** Issue #1, Issue #2
+
+**Description:**
+
+Move test suite from `src/gitea_mcp_remote/tests/` to repository root `tests/` directory and update all test imports to use new package name.
+
+**Tasks:**
+- [ ] Move `src/gitea_mcp_remote/tests/` to `tests/`
+- [ ] Update imports in `tests/conftest.py`
+- [ ] Update imports in `tests/test_config.py`
+- [ ] Update imports in `tests/test_middleware.py`
+- [ ] Update imports in `tests/test_filtering.py`
+- [ ] Update `pytest.ini` to use `testpaths = tests`
+- [ ] Run pytest and verify all tests pass
+
+**Acceptance Criteria:**
+- Tests located at repository root: `tests/`
+- No tests in `src/gitea_mcp_remote/tests/`
+- All test imports use `gitea_mcp_remote` package name
+- All existing tests pass: `pytest tests/ -v`
+- pytest.ini references `testpaths = tests`
+
+**Implementation Reference:**
+See `docs/sprint-proposals/sprint-01-implementation-guide.md` - Phase 3, Issues #5-6
+
+---
+
+## Issue #4: Replace pyproject.toml with Marketplace Dependency
+
+**Title:** `[Sprint 01] build: Add marketplace dependency and update project configuration`
+
+**Estimated Time:** 1 hour
+
+**Labels:**
+- `Type/Build`
+- `Priority/Critical`
+- `Component/Dependencies`
+- `Size/S`
+
+**Dependencies:** Issue #1
+
+**Description:**
+
+Replace pyproject.toml with new configuration including the marketplace Git dependency for gitea-mcp-server.
+
+**Tasks:**
+- [ ] Update `pyproject.toml`:
+  - Add marketplace Git dependency
+  - Update package name to `gitea-mcp-remote`
+  - Change entry point to `gitea-mcp-remote`
+  - Update version to 1.1.0
+  - Update test paths to `testpaths = ["tests"]`
+- [ ] Test installation: `pip install -e .`
+- [ ] Verify marketplace dependency installs
+- [ ] Verify entry point exists: `which gitea-mcp-remote`
+
+**Acceptance Criteria:**
+- pyproject.toml includes marketplace Git dependency
+- Entry point is `gitea-mcp-remote` (not `gitea-http-wrapper`)
+- Can run: `pip install -e .` successfully
+- Marketplace dependency installs from Git repository
+- Command `gitea-mcp-remote` is available
+
+**Implementation Reference:**
+See `docs/sprint-proposals/sprint-01-implementation-guide.md` - Phase 5, Issue #9
+
+---
+
+## Issue #5: Implement MCP HTTP Server
+
+**Title:** `[Sprint 01] feat: Implement MCP Streamable HTTP protocol server`
+
+**Estimated Time:** 4-6 hours
+
+**Labels:**
+- `Type/Feature`
+- `Priority/Critical`
+- `Component/Core`
+- `Size/L` → **BREAKDOWN REQUIRED**
+
+**Dependencies:** Issue #1, Issue #2, Issue #4
+
+**Description:**
+
+**NOTE:** This is a Large (L) task that should be broken down into Medium (M) subtasks:
+
+### Subtask 5.1: Remove Old Server and Create MCP Base Server (2-3 hours)
+- Delete `src/gitea_mcp_remote/server.py`
+- Create `src/gitea_mcp_remote/server_http.py` with:
+  - Imports from marketplace `mcp_server`
+  - GiteaMCPServer class with GiteaClient initialization
+  - Startup/shutdown handlers
+  - Basic route structure
+
+### Subtask 5.2: Implement MCP Protocol Endpoints (2-3 hours)
+- Add HEAD /mcp endpoint (protocol version)
+- Add POST /mcp endpoint (JSON-RPC 2.0 handler)
+- Implement MCP methods:
+  - `initialize`
+  - `tools/list`
+  - `tools/call`
+- Add error handling for JSON-RPC
+
+**Combined Tasks:**
+- [ ] Delete old `server.py`
+- [ ] Create new `server_http.py`
+- [ ] Import from marketplace: `from mcp_server import ...`
+- [ ] Implement GiteaMCPServer class
+- [ ] Implement HEAD /mcp (protocol version)
+- [ ] Implement POST /mcp (JSON-RPC handler)
+- [ ] Implement initialize method
+- [ ] Implement tools/list method with filtering
+- [ ] Implement tools/call method with dispatcher
+- [ ] Keep health endpoints: /health, /healthz, /ping
+- [ ] Add JSON-RPC error handling
+- [ ] Verify imports: `from gitea_mcp_remote.server_http import GiteaMCPServer`
+
+**Acceptance Criteria:**
+- Old `server.py` deleted
+- New `server_http.py` exists
+- Imports from marketplace `mcp_server` package
+- MCP endpoints exist: `POST /mcp`, `HEAD /mcp`
+- Health endpoints exist: `/health`, `/healthz`, `/ping`
+- No subprocess spawning code
+- Can import server module successfully
+- JSON-RPC 2.0 request/response handling works
+
+**Implementation Reference:**
+See `docs/sprint-proposals/sprint-01-implementation-guide.md` - Phase 4, Issues #7-8
+
+**Recommendation:** Create two separate issues (5.1 and 5.2) to keep within M size.
+
+---
+
+## Issue #6: Create Docker Infrastructure
+
+**Title:** `[Sprint 01] build: Create Docker multi-service infrastructure with Caddy`
+
+**Estimated Time:** 3-4 hours
+
+**Labels:**
+- `Type/Build`
+- `Priority/High`
+- `Component/Docker`
+- `Size/M`
+
+**Dependencies:** Issue #4, Issue #5
+
+**Description:**
+
+Create Docker infrastructure with two-service architecture: Python app and Caddy reverse proxy.
+
+**Tasks:**
+- [ ] Create `docker/` directory
+- [ ] Create `docker/docker-compose.yml` with two services (app + caddy)
+- [ ] Create `docker/Dockerfile`:
+  - Install git package
+  - Expose port 8080
+  - Use curl for healthcheck
+  - Install marketplace dependency
+- [ ] Create `docker/Caddyfile`:
+  - HTTPS termination
+  - Proxy to app:8080
+  - MCP endpoint routing
+- [ ] Validate Dockerfile builds
+- [ ] Validate docker-compose configuration
+- [ ] Validate Caddyfile syntax
+
+**Acceptance Criteria:**
+- `docker/docker-compose.yml` has two services (app + caddy)
+- `docker/Dockerfile` installs git and uses port 8080
+- `docker/Caddyfile` exists and proxies to app:8080
+- Can build: `docker build -f docker/Dockerfile -t test .`
+- Can validate: `docker-compose -f docker/docker-compose.yml config`
+- Caddy config validates successfully
+
+**Implementation Reference:**
+See `docs/sprint-proposals/sprint-01-implementation-guide.md` - Phase 6, Issues #11-14
+
+---
+
+## Issue #7: Create Utility Scripts and Server Tests
+
+**Title:** `[Sprint 01] test: Create startup scripts and MCP server tests`
+
+**Estimated Time:** 2-3 hours
+
+**Labels:**
+- `Type/Test`
+- `Priority/Medium`
+- `Component/Tests`
+- `Size/M`
+
+**Dependencies:** Issue #5
+
+**Description:**
+
+Create production utility scripts and comprehensive tests for the new MCP HTTP server.
+
+**Tasks:**
+- [ ] Create `scripts/start.sh` (production startup)
+- [ ] Create `scripts/healthcheck.sh` (Docker healthcheck)
+- [ ] Make scripts executable
+- [ ] Create `tests/test_server_http.py`:
+  - Health endpoint tests
+  - MCP HEAD endpoint test (protocol version)
+  - MCP POST endpoint tests (initialize, tools/list, tools/call)
+  - JSON-RPC error handling tests
+  - Tool filtering integration test
+- [ ] Run new tests and verify they pass
+
+**Acceptance Criteria:**
+- `scripts/start.sh` validates environment and starts server
+- `scripts/healthcheck.sh` checks health endpoint
+- Both scripts are executable
+- `tests/test_server_http.py` exists with comprehensive coverage
+- All new tests pass: `pytest tests/test_server_http.py -v`
+- All existing tests still pass: `pytest tests/ -v`
+
+**Implementation Reference:**
+See `docs/sprint-proposals/sprint-01-implementation-guide.md` - Phase 7-8, Issues #15-16
+
+---
+
+## Issue #8: Create Documentation
+
+**Title:** `[Sprint 01] docs: Create CLAUDE.md and update deployment documentation`
+
+**Estimated Time:** 2-3 hours
+
+**Labels:**
+- `Type/Documentation`
+- `Priority/Medium`
+- `Component/Documentation`
+- `Size/M`
+
+**Dependencies:** All previous issues
+
+**Description:**
+
+Create comprehensive project documentation for Claude Code and update deployment guide with new MCP protocol and Docker structure.
+
+**Tasks:**
+- [ ] Create `CLAUDE.md`:
+  - Project overview
+  - Architecture diagram
+  - Development workflows
+  - MCP protocol notes
+  - Configuration reference
+  - Deployment instructions
+  - Troubleshooting guide
+- [ ] Update `DEPLOYMENT.md`:
+  - Replace custom REST API refs with MCP protocol
+  - Update Docker structure (docker/ directory, two services)
+  - Update marketplace dependency installation
+  - Update Claude Desktop config example
+  - Add MCP protocol debugging section
+- [ ] Verify documentation accuracy
+
+**Acceptance Criteria:**
+- `CLAUDE.md` exists with complete project guidance
+- `DEPLOYMENT.md` updated with MCP protocol references
+- No references to old `/tools/list` or `/tools/call` endpoints
+- Docker paths reference `docker/docker-compose.yml`
+- Claude Desktop config shows `/mcp` endpoint
+- All code examples are accurate
+
+**Implementation Reference:**
+See `docs/sprint-proposals/sprint-01-implementation-guide.md` - Phase 9, Issues #17-18
+
+---
+
+## Issue #9: Final Validation and Integration Testing
+
+**Title:** `[Sprint 01] test: Final validation and integration testing`
+
+**Estimated Time:** 2-3 hours
+
+**Labels:**
+- `Type/Test`
+- `Priority/Critical`
+- `Component/Integration`
+- `Size/M`
+
+**Dependencies:** All previous issues
+
+**Description:**
+
+Run complete validation checklist to ensure all architectural corrections are in place and working correctly.
+
+**Tasks:**
+- [ ] Verify package structure (no gitea_http_wrapper)
+- [ ] Verify no old imports remain
+- [ ] Verify config has all new fields
+- [ ] Verify server has MCP endpoints
+- [ ] Run: `pip install -e .` successfully
+- [ ] Run: `pytest tests/ -v` - all tests pass
+- [ ] Build Docker image successfully
+- [ ] Validate docker-compose configuration
+- [ ] Validate Caddyfile syntax
+- [ ] Test MCP endpoint responds to protocol version request
+- [ ] Test MCP endpoint handles JSON-RPC messages
+- [ ] Document any issues found
+- [ ] Create follow-up issues if needed
+
+**Acceptance Criteria:**
+All 16 validation items pass:
+
+**Package Structure:**
+- [ ] `src/gitea_mcp_remote/` exists (not `gitea_http_wrapper`)
+- [ ] No imports reference `gitea_http_wrapper`
+- [ ] `tests/` is at repository root (not in `src/`)
+
+**Configuration:**
+- [ ] `config/settings.py` has `mcp_auth_mode` field
+- [ ] `config/settings.py` has `gitea_repo: str | None`
+- [ ] HTTP defaults are `0.0.0.0:8080`
+
+**Server Implementation:**
+- [ ] `server_http.py` imports from `mcp_server` package
+- [ ] MCP endpoints exist: `POST /mcp`, `HEAD /mcp`
+- [ ] Health endpoints exist: `/health`, `/healthz`, `/ping`
+- [ ] No subprocess spawning code
+
+**Dependencies:**
+- [ ] `pyproject.toml` has marketplace Git dependency
+- [ ] Entry point is `gitea-mcp-remote` (not `gitea-http-wrapper`)
+- [ ] Can run: `pip install -e .` successfully
+
+**Docker:**
+- [ ] `docker/docker-compose.yml` has two services (app + caddy)
+- [ ] `docker/Dockerfile` installs git and uses port 8080
+- [ ] `docker/Caddyfile` exists and proxies to app:8080
+
+**Tests:**
+- [ ] All tests pass: `pytest tests/`
+
+**Implementation Reference:**
+See `docs/sprint-proposals/sprint-01-implementation-guide.md` - Final Validation section
+
+---
+
+## Issue Dependencies Graph
+
+```
+Issue #1 (Rename + Config)
+    ├─→ Issue #2 (Middleware + Filtering)
+    │       └─→ Issue #3 (Tests)
+    │
+    ├─→ Issue #4 (pyproject.toml)
+    │       ├─→ Issue #5 (MCP Server)
+    │       │       ├─→ Issue #6 (Docker)
+    │       │       └─→ Issue #7 (Scripts + Tests)
+    │       │
+    │       └─→ Issue #3 (Tests)
+    │
+    └─→ All above
+            └─→ Issue #8 (Documentation)
+                    └─→ Issue #9 (Final Validation)
+```
+
+## Execution Order
+
+1. Issue #1 - Rename + Config (Foundation)
+2. Issue #2 - Middleware + Filtering (Supporting modules)
+3. Issue #4 - pyproject.toml (Dependencies before server)
+4. Issue #3 - Tests (Can run in parallel with #4)
+5. Issue #5 - MCP Server (Core implementation) **Consider splitting into 5.1 and 5.2**
+6. Issue #6 - Docker (Deployment infrastructure)
+7. Issue #7 - Scripts + Tests (Validation tools)
+8. Issue #8 - Documentation (After implementation complete)
+9. Issue #9 - Final Validation (Sprint completion)
+
+## Size Distribution
+
+- **Small (1-2h):** Issues #2, #4 (2 issues)
+- **Medium (2-4h):** Issues #1, #3, #6, #7, #8, #9 (6 issues)
+- **Large (4-6h):** Issue #5 (1 issue - SHOULD BE SPLIT)
+
+**Recommendation:** Split Issue #5 into two Medium issues for better tracking and clearer completion criteria.
+
+## Total Estimated Time
+
+- Minimum: 19 hours
+- Maximum: 28 hours
+- Average: 23.5 hours
+- **Sprint Duration:** 1 week (5 working days)
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"

 [project]
 name = "gitea-mcp-remote"
-version = "1.0.0"
+version = "0.2.0"
 description = "HTTP transport wrapper for Gitea MCP server"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -24,14 +24,19 @@ classifiers = [
 ]

 dependencies = [
+    # THE MARKETPLACE PACKAGE — this is the whole point of this repo
+    "gitea-mcp-server @ git+https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace.git#subdirectory=mcp-servers/gitea",
+    # MCP SDK
    "mcp>=0.9.0",
-    "uvicorn>=0.27.0",
+    # HTTP server
+    "uvicorn>=0.30.0",
+    "starlette>=0.38.0",
+    # Config (already used by existing modules)
    "pydantic>=2.0.0",
    "pydantic-settings>=2.0.0",
    "python-dotenv>=1.0.0",
-    "starlette>=0.36.0",
-    # gitea-mcp-server - installed separately (not on PyPI yet)
-    # See: https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace
+    # Auth
+    "pyjwt>=2.8.0",
 ]

 [project.optional-dependencies]
@@ -44,7 +49,7 @@ dev = [
 ]

 [project.scripts]
-gitea-http-wrapper = "gitea_http_wrapper.server:main"
+gitea-mcp-remote = "gitea_mcp_remote.server_http:main"

 [project.urls]
 Homepage = "https://github.com/lmiranda/gitea-mcp-remote"
@@ -55,7 +60,7 @@ where = ["src"]

 [tool.pytest.ini_options]
 asyncio_mode = "auto"
-testpaths = ["src/gitea_http_wrapper/tests"]
+testpaths = ["tests"]
 python_files = ["test_*.py"]
 python_classes = ["Test*"]
 python_functions = ["test_*"]
--- a/pytest.ini
+++ b/pytest.ini
@@ -1,5 +1,5 @@
 [pytest]
-testpaths = src/gitea_http_wrapper/tests
+testpaths = tests
 python_files = test_*.py
 python_classes = Test*
 python_functions = test_*
--- a/requirements.txt
+++ b/requirements.txt
@@ -1,11 +1,17 @@
-# HTTP Transport Wrapper Dependencies
+# THE MARKETPLACE PACKAGE — this is the whole point of this repo
+gitea-mcp-server @ git+https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace.git#subdirectory=mcp-servers/gitea
+
+# MCP SDK
 mcp>=0.9.0
-uvicorn>=0.27.0
-starlette>=0.36.0
+
+# HTTP server
+uvicorn>=0.30.0
+starlette>=0.38.0
+
+# Config (already used by existing modules)
 pydantic>=2.0.0
 pydantic-settings>=2.0.0
 python-dotenv>=1.0.0

-# Official Gitea MCP Server (to be wrapped)
-# Install separately - not on PyPI yet
-# See: https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace
+# Auth
+pyjwt>=2.8.0
--- a/scripts/healthcheck.sh
+++ b/scripts/healthcheck.sh
@@ -0,0 +1,21 @@
+#!/bin/bash
+# Health check script for Gitea MCP Remote
+#
+# Used by Docker healthcheck and monitoring systems.
+# Returns exit code 0 if healthy, 1 if unhealthy.
+
+set -e
+
+HOST="${HTTP_HOST:-localhost}"
+PORT="${HTTP_PORT:-8080}"
+ENDPOINT="http://${HOST}:${PORT}/health"
+
+# Make request and check response
+response=$(curl -sf "$ENDPOINT" 2>/dev/null) || exit 1
+
+# Verify JSON response contains status: ok
+if echo "$response" | grep -q '"status".*"ok"'; then
+    exit 0
+else
+    exit 1
+fi
--- a/scripts/start.sh
+++ b/scripts/start.sh
@@ -0,0 +1,60 @@
+#!/bin/bash
+# Production startup script for Gitea MCP Remote
+#
+# This script validates the environment and starts the server.
+
+set -e
+
+# Colors for output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+NC='\033[0m' # No Color
+
+echo -e "${GREEN}Starting Gitea MCP Remote...${NC}"
+
+# Check required environment variables
+check_required_env() {
+    local var_name=$1
+    if [ -z "${!var_name}" ]; then
+        echo -e "${RED}ERROR: Required environment variable $var_name is not set${NC}"
+        return 1
+    fi
+    echo -e "${GREEN}  $var_name is set${NC}"
+}
+
+echo "Checking required environment variables..."
+MISSING=0
+
+check_required_env "GITEA_URL" || MISSING=1
+check_required_env "GITEA_TOKEN" || MISSING=1
+check_required_env "GITEA_OWNER" || MISSING=1
+
+if [ $MISSING -eq 1 ]; then
+    echo -e "${RED}Missing required environment variables. Exiting.${NC}"
+    echo ""
+    echo "Required variables:"
+    echo "  GITEA_URL    - Gitea server URL (e.g., https://gitea.example.com)"
+    echo "  GITEA_TOKEN  - Gitea API token"
+    echo "  GITEA_OWNER  - Default repository owner"
+    echo ""
+    echo "Optional variables:"
+    echo "  GITEA_REPO   - Default repository name"
+    echo "  AUTH_TOKEN   - Bearer token for MCP endpoint authentication"
+    echo "  HTTP_HOST    - Server host (default: 0.0.0.0)"
+    echo "  HTTP_PORT    - Server port (default: 8080)"
+    exit 1
+fi
+
+# Show optional configuration
+echo ""
+echo "Optional configuration:"
+[ -n "$GITEA_REPO" ] && echo -e "  ${GREEN}GITEA_REPO: $GITEA_REPO${NC}" || echo -e "  ${YELLOW}GITEA_REPO: not set (will use per-request)${NC}"
+[ -n "$AUTH_TOKEN" ] && echo -e "  ${GREEN}AUTH_TOKEN: (set)${NC}" || echo -e "  ${YELLOW}AUTH_TOKEN: not set (no auth required)${NC}"
+echo "  HTTP_HOST: ${HTTP_HOST:-0.0.0.0}"
+echo "  HTTP_PORT: ${HTTP_PORT:-8080}"
+
+# Start the server
+echo ""
+echo -e "${GREEN}Starting server...${NC}"
+exec gitea-mcp-remote
--- a/src/gitea_http_wrapper/init.py
+++ b/src/gitea_http_wrapper/init.py
@@ -1,17 +0,0 @@
-"""
-Gitea HTTP MCP Wrapper
-
-This package provides an HTTP transport wrapper around the official Gitea MCP server.
-It handles configuration loading, tool filtering, and HTTP authentication middleware.
-
-Architecture:
- config/: Configuration loader module
- middleware/: HTTP authentication middleware
- filtering/: Tool filtering for Claude Desktop compatibility
- server.py: Main HTTP MCP server implementation
-"""
-
-from .server import GiteaMCPWrapper, create_app, main
-
-__version__ = "0.1.0"
-__all__ = ["__version__", "GiteaMCPWrapper", "create_app", "main"]
--- a/src/gitea_http_wrapper/config/init.py
+++ b/src/gitea_http_wrapper/config/init.py
@@ -1,5 +0,0 @@
-"""Configuration loader module."""
-
-from .settings import GiteaSettings, load_settings
-
-__all__ = ["GiteaSettings", "load_settings"]
--- a/src/gitea_http_wrapper/server.py
+++ b/src/gitea_http_wrapper/server.py
@@ -1,309 +0,0 @@
-"""HTTP MCP server implementation wrapping Gitea MCP."""
-
-import asyncio
-import json
-import logging
-import os
-import sys
-from pathlib import Path
-from typing import Any
-
-import uvicorn
-from mcp.server import Server
-from mcp.server.stdio import stdio_server
-from starlette.applications import Starlette
-from starlette.requests import Request
-from starlette.responses import JSONResponse
-from starlette.routing import Route
-
-from gitea_http_wrapper.config import GiteaSettings, load_settings
-from gitea_http_wrapper.filtering import ToolFilter
-from gitea_http_wrapper.middleware import (
-    BearerAuthMiddleware,
-    HealthCheckBypassMiddleware,
-)
-
-# Configure logging
-logging.basicConfig(
-    level=logging.INFO,
-    format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
-)
-logger = logging.getLogger(__name__)
-
-
-class GiteaMCPWrapper:
-    """
-    HTTP wrapper around the official Gitea MCP server.
-
-    This class manages:
-    1. Starting the Gitea MCP server as a subprocess with stdio transport
-    2. Proxying HTTP requests to the MCP server
-    3. Filtering tools based on configuration
-    4. Handling responses and errors
-    """
-
-    def __init__(self, settings: GiteaSettings):
-        """
-        Initialize the MCP wrapper.
-
-        Args:
-            settings: Configuration settings for Gitea and HTTP server.
-        """
-        self.settings = settings
-        self.tool_filter = ToolFilter(
-            enabled_tools=settings.enabled_tools_list,
-            disabled_tools=settings.disabled_tools_list,
-        )
-        self.process = None
-        self.reader = None
-        self.writer = None
-
-    async def start_gitea_mcp(self) -> None:
-        """
-        Start the Gitea MCP server as a subprocess.
-
-        The server runs with stdio transport, and we communicate via stdin/stdout.
-        """
-        logger.info("Starting Gitea MCP server subprocess")
-
-        # Set environment variables for Gitea MCP
-        env = os.environ.copy()
-        env.update(self.settings.get_gitea_mcp_env())
-
-        # Start the process
-        # Note: This assumes gitea-mcp-server is installed and on PATH
-        # In production Docker, this should be guaranteed
-        try:
-            self.process = await asyncio.create_subprocess_exec(
-                "gitea-mcp-server",
-                stdin=asyncio.subprocess.PIPE,
-                stdout=asyncio.subprocess.PIPE,
-                stderr=asyncio.subprocess.PIPE,
-                env=env,
-            )
-            self.reader = self.process.stdout
-            self.writer = self.process.stdin
-            logger.info("Gitea MCP server started successfully")
-        except FileNotFoundError:
-            logger.error("gitea-mcp-server not found in PATH")
-            raise RuntimeError(
-                "gitea-mcp-server not found. Ensure it's installed: pip install gitea-mcp-server"
-            )
-
-    async def stop_gitea_mcp(self) -> None:
-        """Stop the Gitea MCP server subprocess."""
-        if self.process:
-            logger.info("Stopping Gitea MCP server subprocess")
-            self.process.terminate()
-            await self.process.wait()
-            logger.info("Gitea MCP server stopped")
-
-    async def send_mcp_request(self, method: str, params: dict[str, Any]) -> dict[str, Any]:
-        """
-        Send a JSON-RPC request to the MCP server.
-
-        Args:
-            method: MCP method name (e.g., "tools/list", "tools/call").
-            params: Method parameters.
-
-        Returns:
-            JSON-RPC response from MCP server.
-
-        Raises:
-            RuntimeError: If MCP server is not running or communication fails.
-        """
-        if not self.writer or not self.reader:
-            raise RuntimeError("MCP server not started")
-
-        # Build JSON-RPC request
-        request = {
-            "jsonrpc": "2.0",
-            "id": 1,
-            "method": method,
-            "params": params,
-        }
-
-        # Send request
-        request_json = json.dumps(request) + "\n"
-        self.writer.write(request_json.encode())
-        await self.writer.drain()
-
-        # Read response
-        response_line = await self.reader.readline()
-        response = json.loads(response_line.decode())
-
-        # Check for JSON-RPC error
-        if "error" in response:
-            logger.error(f"MCP error: {response['error']}")
-            raise RuntimeError(f"MCP error: {response['error']}")
-
-        return response.get("result", {})
-
-    async def list_tools(self) -> dict[str, Any]:
-        """
-        List available tools from MCP server with filtering applied.
-
-        Returns:
-            Filtered tools list response.
-        """
-        response = await self.send_mcp_request("tools/list", {})
-        filtered_response = self.tool_filter.filter_tools_response(response)
-
-        logger.info(
-            f"Listed {len(filtered_response.get('tools', []))} tools "
-            f"(filter: {self.tool_filter.get_filter_stats()['mode']})"
-        )
-        return filtered_response
-
-    async def call_tool(self, tool_name: str, arguments: dict[str, Any]) -> dict[str, Any]:
-        """
-        Call a tool on the MCP server.
-
-        Args:
-            tool_name: Name of tool to call.
-            arguments: Tool arguments.
-
-        Returns:
-            Tool execution result.
-
-        Raises:
-            ValueError: If tool is filtered out.
-        """
-        # Check if tool is allowed
-        if not self.tool_filter.should_include_tool(tool_name):
-            raise ValueError(f"Tool '{tool_name}' is not available (filtered)")
-
-        logger.info(f"Calling tool: {tool_name}")
-        result = await self.send_mcp_request(
-            "tools/call",
-            {"name": tool_name, "arguments": arguments},
-        )
-        return result
-
-
-# Global wrapper instance
-wrapper: GiteaMCPWrapper | None = None
-
-
-async def health_check(request: Request) -> JSONResponse:
-    """Health check endpoint."""
-    return JSONResponse({"status": "healthy"})
-
-
-async def list_tools_endpoint(request: Request) -> JSONResponse:
-    """List available tools."""
-    try:
-        tools = await wrapper.list_tools()
-        return JSONResponse(tools)
-    except Exception as e:
-        logger.exception("Error listing tools")
-        return JSONResponse(
-            {"error": str(e)},
-            status_code=500,
-        )
-
-
-async def call_tool_endpoint(request: Request) -> JSONResponse:
-    """Call a tool."""
-    try:
-        body = await request.json()
-        tool_name = body.get("name")
-        arguments = body.get("arguments", {})
-
-        if not tool_name:
-            return JSONResponse(
-                {"error": "Missing 'name' field"},
-                status_code=400,
-            )
-
-        result = await wrapper.call_tool(tool_name, arguments)
-        return JSONResponse(result)
-    except ValueError as e:
-        # Tool filtered
-        return JSONResponse(
-            {"error": str(e)},
-            status_code=403,
-        )
-    except Exception as e:
-        logger.exception("Error calling tool")
-        return JSONResponse(
-            {"error": str(e)},
-            status_code=500,
-        )
-
-
-async def startup() -> None:
-    """Application startup handler."""
-    global wrapper
-    settings = load_settings()
-    wrapper = GiteaMCPWrapper(settings)
-    await wrapper.start_gitea_mcp()
-    logger.info(f"HTTP MCP server starting on {settings.http_host}:{settings.http_port}")
-
-
-async def shutdown() -> None:
-    """Application shutdown handler."""
-    global wrapper
-    if wrapper:
-        await wrapper.stop_gitea_mcp()
-
-
-# Define routes
-routes = [
-    Route("/health", health_check, methods=["GET"]),
-    Route("/healthz", health_check, methods=["GET"]),
-    Route("/ping", health_check, methods=["GET"]),
-    Route("/tools/list", list_tools_endpoint, methods=["POST"]),
-    Route("/tools/call", call_tool_endpoint, methods=["POST"]),
-]
-
-# Create Starlette app
-app = Starlette(
-    routes=routes,
-    on_startup=[startup],
-    on_shutdown=[shutdown],
-)
-
-
-def create_app(settings: GiteaSettings | None = None) -> Starlette:
-    """
-    Create and configure the Starlette application.
-
-    Args:
-        settings: Optional settings override for testing.
-
-    Returns:
-        Configured Starlette application.
-    """
-    if settings is None:
-        settings = load_settings()
-
-    # Add middleware
-    app.add_middleware(HealthCheckBypassMiddleware)
-    app.add_middleware(BearerAuthMiddleware, auth_token=settings.auth_token)
-
-    return app
-
-
-def main() -> None:
-    """Main entry point for the HTTP MCP server."""
-    settings = load_settings()
-
-    # Log filter configuration
-    filter_stats = ToolFilter(
-        enabled_tools=settings.enabled_tools_list,
-        disabled_tools=settings.disabled_tools_list,
-    ).get_filter_stats()
-    logger.info(f"Tool filtering: {filter_stats}")
-
-    # Run server
-    uvicorn.run(
-        "gitea_http_wrapper.server:app",
-        host=settings.http_host,
-        port=settings.http_port,
-        log_level="info",
-    )
-
-
-if __name__ == "__main__":
-    main()
--- a/src/gitea_mcp_remote/init.py
+++ b/src/gitea_mcp_remote/init.py
@@ -0,0 +1,11 @@
+"""
+Gitea MCP Remote — HTTP deployment wrapper for marketplace Gitea MCP server.
+
+Imports tool definitions from gitea-mcp-server (marketplace) and serves them
+over Streamable HTTP transport with authentication and TLS via Caddy.
+"""
+
+from .server_http import create_app, main
+
+__version__ = "0.2.0"
+__all__ = ["__version__", "create_app", "main"]
--- a/src/gitea_mcp_remote/config/init.py
+++ b/src/gitea_mcp_remote/config/init.py
@@ -0,0 +1,5 @@
+"""Configuration module for Gitea MCP HTTP transport."""
+
+from gitea_mcp_remote.config.settings import GiteaSettings, load_settings
+
+__all__ = ["GiteaSettings", "load_settings"]
--- a/src/gitea_http_wrapper/config/settings.py
+++ b/src/gitea_http_wrapper/config/settings.py
@@ -1,4 +1,4 @@
-"""Configuration settings for Gitea HTTP MCP wrapper."""
+"""Configuration settings for Gitea MCP HTTP transport."""

 from pathlib import Path
 from typing import Optional
@@ -30,18 +30,18 @@ class GiteaSettings(BaseSettings):
        ...,
        description="Default repository owner/organization",
    )
-    gitea_repo: str = Field(
-        ...,
-        description="Default repository name",
+    gitea_repo: str | None = Field(
+        default=None,
+        description="Default repository name (optional)",
    )

    # HTTP Server Configuration
    http_host: str = Field(
-        default="127.0.0.1",
+        default="0.0.0.0",
        description="HTTP server bind address",
    )
    http_port: int = Field(
-        default=8000,
+        default=8080,
        ge=1,
        le=65535,
        description="HTTP server port",
@@ -52,6 +52,10 @@ class GiteaSettings(BaseSettings):
        default=None,
        description="Bearer token for HTTP authentication (optional)",
    )
+    mcp_auth_mode: str = Field(
+        default="optional",
+        description="MCP authentication mode: 'required', 'optional', or 'none'",
+    )

    # Tool Filtering Configuration
    enabled_tools: Optional[str] = Field(
@@ -85,15 +89,6 @@ class GiteaSettings(BaseSettings):
            return None
        return [tool.strip() for tool in self.disabled_tools.split(",") if tool.strip()]

-    def get_gitea_mcp_env(self) -> dict[str, str]:
-        """Get environment variables for the wrapped Gitea MCP server."""
-        return {
-            "GITEA_BASE_URL": self.gitea_url,
-            "GITEA_API_TOKEN": self.gitea_token,
-            "GITEA_DEFAULT_OWNER": self.gitea_owner,
-            "GITEA_DEFAULT_REPO": self.gitea_repo,
-        }
-

 def load_settings(env_file: Optional[Path] = None) -> GiteaSettings:
    """
--- a/src/gitea_http_wrapper/filtering/init.py
+++ b/src/gitea_http_wrapper/filtering/init.py
--- a/src/gitea_http_wrapper/filtering/filter.py
+++ b/src/gitea_http_wrapper/filtering/filter.py
@@ -1,7 +1,10 @@
 """Tool filtering for Claude Desktop compatibility."""

+import logging
 from typing import Any

+logger = logging.getLogger(__name__)
+

 class ToolFilter:
    """
@@ -22,13 +25,11 @@ class ToolFilter:
        Args:
            enabled_tools: List of tool names to enable. If None, all tools are enabled.
            disabled_tools: List of tool names to disable. Takes precedence over enabled_tools.
-
-        Raises:
-            ValueError: If both enabled_tools and disabled_tools are specified.
        """
        if enabled_tools is not None and disabled_tools is not None:
-            raise ValueError(
-                "Cannot specify both enabled_tools and disabled_tools. Choose one filtering mode."
+            logger.warning(
+                "Both enabled_tools and disabled_tools specified. "
+                "Disabled list takes precedence over enabled list."
            )

        self.enabled_tools = set(enabled_tools) if enabled_tools else None
--- a/src/gitea_http_wrapper/middleware/init.py
+++ b/src/gitea_http_wrapper/middleware/init.py
--- a/src/gitea_http_wrapper/middleware/auth.py
+++ b/src/gitea_http_wrapper/middleware/auth.py
--- a/src/gitea_mcp_remote/server_http.py
+++ b/src/gitea_mcp_remote/server_http.py
@@ -0,0 +1,157 @@
+"""
+Gitea MCP Remote — HTTP server with MCP Streamable HTTP protocol.
+
+This module imports tool definitions from the marketplace gitea-mcp-server
+package and serves them over HTTP with authentication.
+"""
+
+import logging
+import asyncio
+from typing import Any
+import uvicorn
+from starlette.applications import Starlette
+from starlette.responses import JSONResponse, Response
+from starlette.routing import Route, Mount
+from mcp.server import Server
+from mcp.server.streamable_http import StreamableHTTPServerTransport
+from mcp.types import Tool, TextContent
+
+from gitea_mcp_remote.config import load_settings
+from gitea_mcp_remote.middleware import BearerAuthMiddleware, HealthCheckBypassMiddleware
+from gitea_mcp_remote.filtering import ToolFilter
+
+# Import marketplace package
+from mcp_server import get_tool_definitions, create_tool_dispatcher, GiteaClient
+
+logger = logging.getLogger(__name__)
+
+
+async def health_check(request):
+    """Health check endpoint - bypasses authentication."""
+    return JSONResponse({"status": "ok"})
+
+
+def create_mcp_server(tool_names: list[str] | None = None) -> Server:
+    """Create and configure the MCP server with tools from the marketplace."""
+    mcp_server = Server("gitea-mcp-remote")
+
+    # Get tool definitions from marketplace
+    tools = get_tool_definitions(tool_filter=tool_names)
+
+    # Create Gitea client and dispatcher
+    gitea_client = GiteaClient()
+    dispatcher = create_tool_dispatcher(gitea_client, tool_filter=tool_names)
+
+    @mcp_server.list_tools()
+    async def list_tools() -> list[Tool]:
+        """Return available Gitea tools."""
+        return tools
+
+    @mcp_server.call_tool()
+    async def call_tool(name: str, arguments: dict) -> list[TextContent]:
+        """Execute a tool with the given arguments."""
+        return await dispatcher(name, arguments)
+
+    return mcp_server
+
+
+def create_app():
+    """Create the Starlette application with middleware."""
+    settings = load_settings()
+
+    # Set up tool filtering
+    tool_filter = ToolFilter(
+        enabled_tools=settings.enabled_tools_list,
+        disabled_tools=settings.disabled_tools_list,
+    )
+
+    # Convert to list for marketplace API
+    tool_names = None  # means "all"
+    if tool_filter.enabled_tools:
+        tool_names = list(tool_filter.enabled_tools)
+
+    # Create MCP server with filtered tools
+    mcp_server = create_mcp_server(tool_names)
+
+    # Store server for endpoint access
+    app_state = {"mcp_server": mcp_server}
+
+    class MCPEndpoint:
+        """ASGI app wrapper for MCP protocol endpoint."""
+
+        async def __call__(self, scope, receive, send):
+            """Handle MCP requests - both POST and HEAD."""
+            method = scope.get("method", "")
+
+            if method == "HEAD":
+                # Return protocol version header
+                await send({
+                    "type": "http.response.start",
+                    "status": 200,
+                    "headers": [
+                        [b"x-mcp-protocol-version", b"2024-11-05"],
+                    ],
+                })
+                await send({
+                    "type": "http.response.body",
+                    "body": b"",
+                })
+                return
+
+            # For POST requests, use the StreamableHTTPServerTransport
+            # Create transport for this request
+            transport = StreamableHTTPServerTransport(mcp_session_id=None)
+
+            # Run the MCP server with this transport
+            async with transport.connect() as (read_stream, write_stream):
+                # Start server task
+                server_task = asyncio.create_task(
+                    app_state["mcp_server"].run(
+                        read_stream,
+                        write_stream,
+                        app_state["mcp_server"].create_initialization_options()
+                    )
+                )
+
+                # Handle the HTTP request
+                try:
+                    await transport.handle_request(scope, receive, send)
+                finally:
+                    # Cancel server task if still running
+                    if not server_task.done():
+                        server_task.cancel()
+                        try:
+                            await server_task
+                        except asyncio.CancelledError:
+                            pass
+
+    # Create MCP endpoint instance
+    mcp_endpoint = MCPEndpoint()
+
+    routes = [
+        Route("/health", health_check, methods=["GET"]),
+        Route("/mcp", mcp_endpoint, methods=["GET", "POST", "HEAD"]),
+    ]
+
+    app = Starlette(routes=routes)
+
+    # Apply middleware (order matters - outermost runs first)
+    # HealthCheckBypass must wrap BearerAuth so it sets skip_auth flag first
+    if settings.auth_token:
+        app = BearerAuthMiddleware(app, auth_token=settings.auth_token)
+    app = HealthCheckBypassMiddleware(app)
+
+    return app
+
+
+def main():
+    """Entry point for the gitea-mcp-remote command."""
+    settings = load_settings()
+    app = create_app()
+
+    logger.info(f"Starting Gitea MCP Remote on {settings.http_host}:{settings.http_port}")
+    uvicorn.run(app, host=settings.http_host, port=settings.http_port)
+
+
+if __name__ == "__main__":
+    main()
--- a/src/gitea_http_wrapper/tests/init.py
+++ b/src/gitea_http_wrapper/tests/init.py
--- a/src/gitea_http_wrapper/tests/conftest.py
+++ b/src/gitea_http_wrapper/tests/conftest.py
--- a/src/gitea_http_wrapper/tests/test_config.py
+++ b/src/gitea_http_wrapper/tests/test_config.py
@@ -6,7 +6,7 @@ from pathlib import Path
 import pytest
 from pydantic import ValidationError

-from gitea_http_wrapper.config import GiteaSettings, load_settings
+from gitea_mcp_remote.config import GiteaSettings, load_settings


 class TestGiteaSettings:
@@ -36,9 +36,10 @@ class TestGiteaSettings:
        assert settings.gitea_token == "test_token"
        assert settings.gitea_owner == "test_owner"
        assert settings.gitea_repo == "test_repo"
-        assert settings.http_host == "127.0.0.1"
-        assert settings.http_port == 8000
+        assert settings.http_host == "0.0.0.0"
+        assert settings.http_port == 8080
        assert settings.auth_token is None
+        assert settings.mcp_auth_mode == "optional"

    def test_gitea_url_validation(self):
        """Test Gitea URL validation."""
@@ -152,21 +153,24 @@ class TestGiteaSettings:
        )
        assert settings.disabled_tools_list == ["tool1", "tool2"]

-    def test_get_gitea_mcp_env(self):
-        """Test environment variable generation for wrapped MCP server."""
+    def test_mcp_auth_mode_field(self):
+        """Test mcp_auth_mode field with different values."""
        settings = GiteaSettings(
            gitea_url="https://gitea.example.com",
            gitea_token="test_token",
            gitea_owner="test_owner",
-            gitea_repo="test_repo",
+            mcp_auth_mode="required",
        )

-        env = settings.get_gitea_mcp_env()
+        assert settings.mcp_auth_mode == "required"

-        assert env["GITEA_BASE_URL"] == "https://gitea.example.com"
-        assert env["GITEA_API_TOKEN"] == "test_token"
-        assert env["GITEA_DEFAULT_OWNER"] == "test_owner"
-        assert env["GITEA_DEFAULT_REPO"] == "test_repo"
+        # Default value
+        settings_default = GiteaSettings(
+            gitea_url="https://gitea.example.com",
+            gitea_token="test_token",
+            gitea_owner="test_owner",
+        )
+        assert settings_default.mcp_auth_mode == "optional"


 class TestLoadSettings:
--- a/src/gitea_http_wrapper/tests/test_filtering.py
+++ b/src/gitea_http_wrapper/tests/test_filtering.py
@@ -2,18 +2,24 @@

 import pytest

-from gitea_http_wrapper.filtering import ToolFilter
+from gitea_mcp_remote.filtering import ToolFilter


 class TestToolFilter:
    """Test ToolFilter class."""

-    def test_init_with_both_lists_raises(self):
-        """Test that specifying both enabled and disabled lists raises error."""
-        with pytest.raises(ValueError) as exc_info:
-            ToolFilter(enabled_tools=["tool1"], disabled_tools=["tool2"])
+    def test_init_with_both_lists_logs_warning(self, caplog):
+        """Test that specifying both enabled and disabled lists logs warning."""
+        import logging

-        assert "Cannot specify both" in str(exc_info.value)
+        with caplog.at_level(logging.WARNING):
+            filter = ToolFilter(enabled_tools=["tool1"], disabled_tools=["tool2"])
+
+        assert "Both enabled_tools and disabled_tools specified" in caplog.text
+        assert "Disabled list takes precedence" in caplog.text
+
+        # Verify disabled list takes precedence
+        assert not filter.should_include_tool("tool2")

    def test_passthrough_mode(self):
        """Test passthrough mode (no filtering)."""
--- a/tests/test_mcp_endpoints.py
+++ b/tests/test_mcp_endpoints.py
@@ -0,0 +1,137 @@
+"""Tests for MCP protocol endpoints and health checks."""
+import pytest
+import json
+import re
+from starlette.testclient import TestClient
+from gitea_mcp_remote.server_http import create_app
+from unittest.mock import patch
+
+
+@pytest.fixture
+def mock_env():
+    """Mock environment variables for testing."""
+    env = {
+        "GITEA_URL": "https://gitea.example.com",
+        "GITEA_TOKEN": "test_token",
+        "GITEA_OWNER": "test_owner",
+    }
+    with patch.dict("os.environ", env):
+        yield env
+
+
+@pytest.fixture
+def client(mock_env):
+    """Create test client."""
+    app = create_app()
+    return TestClient(app)
+
+
+# =============================================================================
+# Health Endpoint Tests
+# =============================================================================
+
+
+def test_health_endpoint(client):
+    """Test GET /health returns status ok."""
+    response = client.get("/health")
+    assert response.status_code == 200
+    data = response.json()
+    assert data["status"] == "ok"
+
+
+def test_health_endpoint_no_auth_required(mock_env):
+    """Test health endpoint works even with AUTH_TOKEN set."""
+    with patch.dict("os.environ", {**mock_env, "AUTH_TOKEN": "secret123"}):
+        app = create_app()
+        client = TestClient(app)
+        # Health should bypass auth
+        response = client.get("/health")
+        assert response.status_code == 200
+        assert response.json()["status"] == "ok"
+
+
+# =============================================================================
+# MCP Protocol Tests
+# =============================================================================
+
+
+def parse_sse_message(sse_text: str) -> dict:
+    """Parse SSE message data."""
+    data_match = re.search(r'data: (.+)', sse_text)
+    if data_match:
+        return json.loads(data_match.group(1))
+    return None
+
+
+def test_mcp_head_endpoint(client):
+    """Test HEAD /mcp returns protocol version header."""
+    response = client.head("/mcp")
+    assert response.status_code == 200
+    assert "x-mcp-protocol-version" in response.headers
+    assert response.headers["x-mcp-protocol-version"] == "2024-11-05"
+
+
+def test_mcp_initialize(client):
+    """Test MCP initialize request."""
+    initialize_request = {
+        "jsonrpc": "2.0",
+        "id": 1,
+        "method": "initialize",
+        "params": {
+            "protocolVersion": "2024-11-05",
+            "capabilities": {},
+            "clientInfo": {
+                "name": "test-client",
+                "version": "1.0.0"
+            }
+        }
+    }
+
+    response = client.post(
+        "/mcp",
+        json=initialize_request,
+        headers={
+            "Content-Type": "application/json",
+            "Accept": "application/json, text/event-stream"
+        }
+    )
+
+    assert response.status_code == 200
+
+    # Parse SSE response
+    data = parse_sse_message(response.text)
+    assert data is not None
+    assert data.get("jsonrpc") == "2.0"
+    assert "result" in data
+    assert data["result"].get("protocolVersion") == "2024-11-05"
+    assert "serverInfo" in data["result"]
+    assert data["result"]["serverInfo"]["name"] == "gitea-mcp-remote"
+
+
+def test_mcp_missing_accept_header(client):
+    """Test MCP request without required Accept header."""
+    initialize_request = {
+        "jsonrpc": "2.0",
+        "id": 1,
+        "method": "initialize",
+        "params": {
+            "protocolVersion": "2024-11-05",
+            "capabilities": {},
+            "clientInfo": {
+                "name": "test-client",
+                "version": "1.0.0"
+            }
+        }
+    }
+
+    response = client.post(
+        "/mcp",
+        json=initialize_request,
+        headers={
+            "Content-Type": "application/json",
+            "Accept": "application/json"  # Missing text/event-stream
+        }
+    )
+
+    # Should return error about missing accept header
+    assert response.status_code == 406
--- a/src/gitea_http_wrapper/tests/test_middleware.py
+++ b/src/gitea_http_wrapper/tests/test_middleware.py
@@ -6,7 +6,7 @@ from starlette.responses import JSONResponse
 from starlette.routing import Route
 from starlette.testclient import TestClient

-from gitea_http_wrapper.middleware import (
+from gitea_mcp_remote.middleware import (
    BearerAuthMiddleware,
    HealthCheckBypassMiddleware,
 )
Author	SHA1	Message	Date
lmiranda	2dbb66deae	docs: Create CLAUDE.md and update deployment documentation (#27 ) - 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>	2026-02-03 21:32:39 -05:00
lmiranda	88c16c840b	feat: Add Docker infrastructure with Caddy and startup scripts (#25 , #26 ) Issue #25 - Docker multi-service infrastructure: - Create docker/Dockerfile with multi-stage build, git support, port 8080 - Create docker/docker-compose.yml with app + Caddy services - Create docker/Caddyfile for HTTPS termination and reverse proxy - Create docker/.env.example with configuration template Issue #26 - Startup scripts and tests: - Create scripts/start.sh for production startup with env validation - Create scripts/healthcheck.sh for Docker health checks - Add health endpoint tests to test_mcp_endpoints.py - Fix middleware order (HealthCheckBypass must wrap BearerAuth) - Fix pyproject.toml testpaths to use 'tests' directory - Update test_config.py for new defaults (0.0.0.0:8080) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>	2026-02-03 21:11:29 -05:00
lmiranda	9fea0683f7	Merge feat/24: Implement MCP Streamable HTTP protocol endpoints	2026-02-03 18:16:51 -05:00
lmiranda	a5390a3086	feat: implement MCP Streamable HTTP protocol endpoints - Add POST /mcp endpoint using StreamableHTTPServerTransport - Add HEAD /mcp endpoint returning protocol version header - Remove old custom REST endpoints (/tools/list, /tools/call) - Integrate marketplace tools via MCP Server decorators - Add comprehensive MCP endpoint tests - Update README with correct MCP protocol usage The implementation properly handles: - JSON-RPC 2.0 message format - SSE (Server-Sent Events) responses - Protocol version negotiation - Tool filtering integration - Authentication middleware Tests verify: - HEAD /mcp returns correct headers - POST /mcp handles initialize requests - Proper error handling for missing headers Closes #24 Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>	2026-02-03 18:16:48 -05:00
lmiranda	c3caf4e169	Merge feat/21-move-tests: Move tests to repository root	2026-02-03 18:08:58 -05:00
lmiranda	cd8718c114	Move tests to repository root and update pytest configuration - Move tests from src/gitea_mcp_remote/tests/ to tests/ (top-level) - Update pytest.ini to point to new test location - All imports already use absolute paths (gitea_mcp_remote.*) - Tests run successfully from new location (28/30 pass, 2 pre-existing failures) This improves project structure by following standard Python conventions where tests live at the repository root level rather than inside the source package. Closes #21 Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>	2026-02-03 18:08:54 -05:00
lmiranda	53a0006a3f	Merge feat/23: Remove old server and create MCP base server structure	2026-02-03 18:07:55 -05:00
lmiranda	fb8cc08112	feat: Remove old server and create MCP base server structure - Delete old subprocess-based server.py - Create new server_http.py with base structure for MCP Streamable HTTP protocol - Update __init__.py to import from server_http - Health check endpoint in place - Middleware integration ready for MCP endpoints Issue #24 will add the actual MCP protocol endpoints. Closes #23 Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>	2026-02-03 18:07:51 -05:00
lmiranda	809eef132a	feat: add marketplace dependency and update project config - Add gitea-mcp-server git dependency from marketplace - Update version to 0.2.0 - Update entry point to server_http:main - Add MCP and Caddy environment variables to .env.example - Update uvicorn and starlette versions - Add pyjwt for authentication - Regenerate requirements.txt with all dependencies Closes #22 Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>	2026-02-03 18:05:07 -05:00
lmiranda	1c55eed7c0	Merge feat/19: Rename package to gitea_mcp_remote and update configuration	2026-02-03 18:00:38 -05:00
lmiranda	5075139841	refactor: Rename package to gitea_mcp_remote and update configuration Issue #19 - Foundation for Sprint 01: Core Architecture Correction Changes: - Renamed package directory: gitea_http_wrapper -> gitea_mcp_remote - Updated config/settings.py: - Made gitea_repo optional (allow None) - Added mcp_auth_mode field (default: "optional") - Changed HTTP defaults: 0.0.0.0:8080 (was 127.0.0.1:8000) - Removed get_gitea_mcp_env() method (no longer needed) - Updated all import paths throughout codebase - Updated filtering/filter.py: Changed ValueError to warning when both enabled_tools and disabled_tools are specified - Updated test files with new import paths - Updated test_filtering.py to test warning instead of ValueError - Updated pyproject.toml, pytest.ini, and README.md references All modules preserved - only import paths and configuration updated. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>	2026-02-03 17:59:57 -05:00
lmiranda	16436c847a	docs: Add Sprint 01 planning documentation Create comprehensive sprint planning documentation for Core Architecture Correction sprint. This addresses three fatal architectural problems from v1.0.0 release. Sprint documents include: - Executive proposal with architecture analysis - Detailed implementation guide with code snippets - Issue breakdown with dependencies - Sprint summary with approval checklist Sprint creates 10 issues in Gitea milestone 29: - Issues #19-28 covering package rename, MCP protocol implementation, Docker infrastructure, testing, and documentation - Total estimated effort: 19-28 hours (1 week sprint) - All issues properly sized (S/M), labeled, and dependency-tracked This is attempt #3 - all details from architectural correction prompt have been captured. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>	2026-02-03 17:53:59 -05:00