Cleanup

Author: SPerekrestova

.env.example

@@ -1,11 +1,3 @@
 # GitHub Configuration
 GITHUB_TOKEN=ghp_your_token_here
 GITHUB_API_BASE_URL=https://api.github.com
-
-# Server Configuration
-MCP_SERVER_PORT=7860
-LOG_LEVEL=INFO
-
-# Docker BuildKit (enable for faster builds with cache mounts)
-DOCKER_BUILDKIT=1
-COMPOSE_DOCKER_CLI_BUILD=1

CLAUDE.md

@@ -2,147 +2,57 @@
 
 This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
 
-## Overview
+## Project Overview
 
-GitHub MCP Server is a Model Context Protocol (MCP) server that provides access to GitHub documentation via the GitHub API. It's built with FastMCP and runs as a stdio-based MCP server, designed to be integrated with Claude Desktop or other MCP clients.
+GitHub MCP Server - A Model Context Protocol (MCP) server that provides GitHub API access for fetching and searching documentation in `/doc` folders across GitHub organizations. Built with FastMCP.
 
 ## Development Commands
 
-### Environment Setup
-
 ```bash
-# Create and activate virtual environment
+# Setup
 python3 -m venv .venv
-source .venv/bin/activate  # On Windows: .venv\Scripts\activate
-
-# Install dependencies
+source .venv/bin/activate
 pip install -r requirements.txt
+cp .env.example .env  # Add GITHUB_TOKEN
 
-# Configure environment
-cp .env.example .env
-# Edit .env and add your GITHUB_TOKEN
-```
-
-### Running the Server
-
-```bash
-# Run directly with Python (stdio mode for MCP)
+# Run locally (stdio transport for Claude Desktop)
 python main.py
 
-# Run with Docker
-docker build -t github-mcp-server:local .
-docker run -i --rm -e GITHUB_TOKEN='your_token' github-mcp-server:local
-
-# Run with docker-compose
-docker-compose build
-docker-compose up
+# Run with HTTP transport (for Hugging Face Spaces)
+# Set MCP_HTTP_TRANSPORT=true or modify main.py to use mcp.run(transport="http")
 ```
 
-### Docker Build Performance
-
-The Dockerfile is optimized for fast rebuilds (10-20x faster):
-- Uses BuildKit for layer caching
-- Separates dependency installation from code copying
-- Enable BuildKit: `export DOCKER_BUILDKIT=1`
-
 ## Architecture
 
-### Single-File Architecture
-
-The entire server is implemented in `main.py` (~650 lines) with a clear functional organization:
+**Single-file MCP server** (`main.py`) using FastMCP framework:
 
-1. **Configuration & Setup** (lines 1-37): Environment loading, logging, MCP initialization
-2. **Helper Functions** (lines 39-114): GitHub API headers, /doc folder detection, content type determination
-3. **Business Logic Functions** (lines 116-442): Core async functions that implement GitHub API interactions
-4. **MCP Tools Registration** (lines 444-569): Decorated wrappers that expose business logic as MCP tools
-5. **MCP Resources** (lines 571-638): URI-based resource handlers for documentation access
-6. **Main Entry Point** (lines 640-652): Server startup
+1. **MCP Tools** (decorated with `@mcp.tool()`):
+   - `get_org_repos_tool` - List repos with `/doc` folder detection (uses Search API first, falls back to listing all)
+   - `get_repo_docs_tool` - Get documentation files from repo's `/doc` folder
+   - `get_file_content_tool` - Fetch and decode file content (handles base64)
+   - `search_documentation_tool` - Search docs across org using GitHub Code Search API
 
-### Key Design Patterns
+2. **MCP Resources** (decorated with `@mcp.resource()`):
+   - `documentation://{org}/{repo}` - List docs
+   - `content://{org}/{repo}/{path}` - Get file content
 
-**Separation of Concerns**: Business logic functions (e.g., `get_org_repos()`) are separate from MCP tool decorators (e.g., `get_org_repos_tool()`). This allows the core logic to be testable independently of MCP.
+3. **Business Logic Functions** (async, testable):
+   - `get_org_repos()`, `get_repo_docs()`, `get_file_content()`, `search_documentation()`
+   - Each tool is a thin wrapper calling these functions
 
-**Async/Await Throughout**: All GitHub API interactions use `aiohttp` for async HTTP requests. Functions reuse `ClientSession` objects for connection pooling.
+## Key Implementation Details
 
-**Two-Strategy Approach**: `get_org_repos()` tries GitHub Search API first (efficient, one request), then falls back to listing all repos individually if search fails.
+- **GitHub API strategy**: Search API first for efficiency, fallback to paginated list + check each repo
+- **Supported doc types**: `.md`, `.mmd`, `.mermaid`, `.svg`, `.yml`, `.yaml`, `.json`
+- **Content decoding**: Base64 content from GitHub API is automatically decoded
+- **Health check**: `/health` endpoint available via `@mcp.custom_route()`
 
-**Base64 Decoding**: GitHub API returns file content as base64-encoded strings. The `get_file_content()` function automatically decodes this to UTF-8 text.
+## Environment Variables
 
-## MCP Integration
-
-### Tools (4 total)
-
-- `get_org_repos_tool(org)` - Lists repositories with /doc folder detection
-- `get_repo_docs_tool(org, repo)` - Lists documentation files in a repo's /doc folder
-- `get_file_content_tool(org, repo, path)` - Fetches and decodes file content
-- `search_documentation_tool(org, query)` - Searches docs across repos using GitHub Code Search API
-
-### Resources (2 patterns)
-
-- `documentation://{org}/{repo}` - Lists documentation files in formatted text
-- `content://{org}/{repo}/{path}` - Returns raw file content
-
-### Environment Variables
-
-Required:
-- `GITHUB_TOKEN` - GitHub personal access token (scopes: `repo`, `read:org`, `read:user`)
-
-Optional:
+- `GITHUB_TOKEN` - Required for API access (scopes: `repo`, `read:org`, `read:user`)
 - `GITHUB_API_BASE_URL` - Default: `https://api.github.com`
 - `LOG_LEVEL` - Default: `INFO`
-- `MCP_SERVER_PORT` - Default: `8000` (note: not used in stdio mode)
-
-## Supported File Types
-
-The server filters for specific documentation file types in /doc folders:
-- Markdown: `.md`
-- Mermaid diagrams: `.mmd`, `.mermaid`
-- SVG images: `.svg`
-- OpenAPI specs: `.yml`, `.yaml`, `.json`
-- Postman collections: `.json` (filename must start with "postman")
-
-## Error Handling
-
-- 404 responses return empty lists or specific error messages
-- Rate limiting (403 from Search API) returns user-facing error message
-- All GitHub API errors include status code and response text
-- Missing GITHUB_TOKEN triggers warning but allows unauthenticated requests (with rate limits)
-
-## Claude Desktop Configuration
-
-Add to `claude_desktop_config.json`:
-
-**Docker deployment:**
-```json
-{
-  "mcpServers": {
-    "github-docs": {
-      "command": "docker",
-      "args": ["run", "-i", "--rm", "-e", "GITHUB_TOKEN", "ghcr.io/sperekrestova/github-mcp-server:latest"],
-      "env": {"GITHUB_TOKEN": "ghp_your_token_here"}
-    }
-  }
-}
-```
-
-**Python deployment:**
-```json
-{
-  "mcpServers": {
-    "github-docs": {
-      "command": "python3",
-      "args": ["/absolute/path/to/main.py"],
-      "env": {"GITHUB_TOKEN": "ghp_your_token_here"}
-    }
-  }
-}
-```
 
-## Testing Approach
+## CI/CD
 
-Currently no test suite exists. When adding tests:
-- Test business logic functions separately from MCP tool wrappers
-- Mock `aiohttp.ClientSession` for GitHub API interactions
-- Test base64 decoding edge cases in `get_file_content()`
-- Test /doc folder detection logic
-- Test file type filtering against supported extensions
+Docker image published to `ghcr.io/sperekrestova/github-mcp-server` on push to main or version tags. Multi-platform build (amd64/arm64).

Dockerfile

@@ -10,14 +10,11 @@
 from typing import List, Dict, Any
 
 import aiohttp
-import gradio as gr
 from fastmcp import FastMCP
 from starlette.requests import Request
 from starlette.responses import PlainTextResponse
 
 LOG_LEVEL = os.getenv("LOG_LEVEL", "INFO")
-SERVER_PORT = int(os.getenv("SERVER_PORT", "8003"))
-SERVER_HOST = os.getenv("MCP_SERVER_HOST", "0.0.0.0")
 GITHUB_TOKEN = os.getenv("GITHUB_TOKEN", "random")
 GITHUB_API_BASE = os.getenv("GITHUB_API_BASE_URL", "https://api.github.com")
 
@@ -537,143 +534,15 @@ async def content_resource(org: str, repo: str, path: str) -> str:
     file_data = await get_file_content(org, repo, path)
     return file_data["content"]
 
-# Create Gradio Interface
-def create_gradio_interface():
-    """Create Gradio interface to display MCP server information"""
-
-    async def get_server_info():
-        """Get server status and information"""
-        # Get tools using await (Gradio supports async functions)
-        tools_dict = await mcp.get_tools()
-        tools_list = list(tools_dict.values())
-
-        # Build tools information
-        tools_info = f"## 🛠️ Available MCP Tools ({len(tools_list)})\n\n"
-        for tool in tools_list:
-            tools_info += f"### {tool.name}\n"
-            tools_info += f"{tool.description or 'No description available'}\n\n"
-
-            if hasattr(tool, 'parameters') and tool.parameters:
-                if hasattr(tool.parameters, 'properties'):
-                    params = list(tool.parameters.properties.keys())
-                    tools_info += f"**Parameters:** {', '.join(f'`{p}`' for p in params)}\n\n"
-
-        return tools_info
-
-    async def check_mcp_status():
-        """Check if MCP endpoint is responding"""
-        try:
-            # Try to get tools to verify MCP server is working
-            tools_dict = await mcp.get_tools()
-            tool_count = len(tools_dict)
-            return f"✅ MCP Server is running and responding\n✅ {tool_count} tools available at `/mcp` endpoint"
-        except Exception as e:
-            return f"❌ MCP Server error: {str(e)}"
-
-    with gr.Blocks(title="GitHub MCP Server") as demo:
-        demo.theme = gr.themes.Soft()
-        gr.Markdown(
-            """
-            # 🐙 GitHub MCP Server
-
-            Model Context Protocol server for accessing GitHub documentation via API.
-            """
-        )
-
-        with gr.Tab("📡 MCP Endpoint"):
-            gr.Markdown(
-                """
-                ### Connection Information
-
-                **Endpoint:** `/mcp`
-                **Protocol:** MCP over HTTP (Streamable HTTP)
-                **Status:** Active
-
-                ### How to Connect
-
-                **Claude Desktop (Pro/Max/Team):**
-                1. Open Settings → Connectors → Add Custom Integration
-                2. Enter this Space's URL + `/mcp`
-                3. Example: `https://your-username-space-name.hf.space/mcp`
-
-                **Claude Desktop (Free tier):**
-                Use `mcp-remote` proxy in your `claude_desktop_config.json`:
-                ```json
-                {
-                  "mcpServers": {
-                    "github-docs-remote": {
-                      "command": "npx",
-                      "args": ["-y", "mcp-remote", "https://your-space-url.hf.space/mcp"]
-                    }
-                  }
-                }
-                ```
-                """
-            )
-
-            status_btn = gr.Button("Check MCP Status", variant="primary")
-            status_output = gr.Textbox(label="Status", interactive=False)
-            status_btn.click(check_mcp_status, outputs=status_output)
-
-        with gr.Tab("🛠️ Available Tools"):
-            gr.Markdown("View all available MCP tools and their parameters.")
-
-            tools_btn = gr.Button("Load Tools", variant="primary")
-            tools_output = gr.Markdown()
-            tools_btn.click(get_server_info, outputs=tools_output)
-
-        with gr.Tab("📚 Resources"):
-            gr.Markdown(
-                """
-                ### MCP Resources
-
-                This server provides MCP resources for accessing documentation:
-
-                - `documentation://{org}/{repo}` - List documentation files in a repository
-                - `content://{org}/{repo}/{path}` - Get content of a specific file
-
-                ### Supported File Types
-
-                - Markdown (`.md`)
-                - Mermaid diagrams (`.mmd`, `.mermaid`)
-                - SVG images (`.svg`)
-                - OpenAPI specs (`.yml`, `.yaml`, `.json`)
-                - Postman collections (`.json`)
-                """
-            )
-
-        with gr.Tab("ℹ️ About"):
-            gr.Markdown(
-                f"""
-                ### Server Information
-
-                **GitHub Token:** {'✅ Configured' if GITHUB_TOKEN else '❌ Not configured'}
-                **Port:** {SERVER_PORT}
-                **API Base:** {GITHUB_API_BASE}
-
-                ### Links
-
-                - [FastMCP Documentation](https://github.com/jlowin/fastmcp)
-                - [MCP Protocol Specification](https://modelcontextprotocol.io)
-                - [Source Code](https://github.com/SPerekrestova/GitHub_MCP_Server)
-                """
-            )
-
-    return demo
-
 # Add health check endpoint
 @mcp.custom_route("/health", methods=["GET"])
 async def health_check(request: Request) -> PlainTextResponse:
     return PlainTextResponse("OK")
 
-# Create Gradio blocks
-gradio_blocks = create_gradio_interface()
-
 
 # ============================================================================
 # Main Entry Point
 # ============================================================================
 
 if __name__ == "__main__":
-    #gradio_blocks.launch(share=True)
     mcp.run()

docker-compose.yml

@@ -3,6 +3,4 @@ aiohttp>=3.13.3
 python-dotenv>=1.0.0
 pydantic>=2.0.0
 uvicorn[standard]>=0.27.0
-gradio>=4.0.0
-starlette
-fastapi
+starlette