Documentation Generator MCP Server

{ "feature_name": "mcp-http-server", "version": "1.0.0", "status": "ready_for_implementation", "generated_at": "2025-10-16T04:20:00Z", "0_preparation": { "foundation_docs": {"available": ["README.md","API.md","ARCHITECTURE.md","COMPONENTS.md","SCHEMA.md","USER-GUIDE.md"], "missing": []}, "coding_standards": {"available": ["BEHAVIOR-STANDARDS.md","UI-STANDARDS.md","UX-PATTERNS.md","COMPONENT-INDEX.md"], "missing": ["COMPONENT-PATTERN.md"]}, "reference_components": {"primary": "handle_add_changelog_entry - MCP handler pattern", "secondary": ["ErrorResponse factory","Flask patterns","JSON-RPC 2.0"]}, "key_patterns_identified": ["All handlers: log→validate→work→return→catch errors","ErrorResponse factory for consistent errors","Tool dispatcher via TOOL_HANDLERS dict"], "technology_stack": {"language": "Python 3.11+", "frameworks": ["Flask","MCP SDK"], "key_libraries": ["flask==3.0.0","mcp==1.0.0+","pydantic==2.0.0+"]}, "gaps_and_risks": ["Greenfield HTTP wrapper","MCP requires JSON-RPC 2.0 over HTTP/SSE","Railway.app needs PORT env var"] }, "1_executive_summary": { "purpose": "Enable ChatGPT to directly invoke all 23 docs-mcp tools through public HTTPS endpoints via MCP protocol, eliminating need for separate SDK integration and allowing ChatGPT users to access documentation generation, changelog management, standards extraction, and project inventory capabilities from familiar ChatGPT interface", "value_proposition": ["Extends reach to 100M+ ChatGPT users without rebuilding tools", "ChatGPT Developer Mode has native MCP support", "Teams can use docs-mcp from ChatGPT interface seamlessly"], "real_world_analogy": "Like adding phone number to restaurant - same kitchen/food, accessible through new channel. ChatGPT calls endpoint, requests tool, gets JSON results back", "use_case": "User opens ChatGPT Developer Mode → asks 'analyze my project' → ChatGPT calls MCP HTTP endpoint → server runs establish_standards → returns JSON → ChatGPT displays results", "output": "http_server.py Flask app, Procfile for Railway, updated requirements.txt, .env.railway.example, comprehensive test suite, integration documentation" }, "2_risk_assessment": { "overall_risk": "medium", "complexity": "medium (8-12 files, 800-1200 lines, adapts existing patterns)", "scope": "Medium - HTTP layer wrapping tool_handlers.py, no business logic changes", "file_system_risk": "low", "dependencies": ["flask==3.0.0","mcp==1.0.0+","pydantic==2.0.0+","python-dotenv==1.0.0"], "performance_concerns": ["Long tools may timeout on Railway 60s limit - acceptable MVP", "No caching - each request re-executes - acceptable v1", "Large projects may exceed memory - will document limitations"], "security_considerations": ["Open endpoint v1 acceptance, v2 adds auth", "Tool args passed to handlers - existing validation applies", "Must validate project_path for traversal", "Sensitive outputs already masked by tools"], "breaking_changes": "none" }, "3_current_state_analysis": { "affected_files": ["NEW: http_server.py (~300-400 lines)","NEW: http_handlers.py (~200 lines)","NEW: Procfile (3 lines)","NEW: .env.railway.example (5 lines)","NEW: tests/test_http_server.py (~200 lines)","MODIFIED: requirements.txt (add flask,mcp,pydantic,python-dotenv)","MODIFIED: README.md (HTTP server section, deployment)"], "dependencies": { "existing_internal": ["server.py - tool definitions","tool_handlers.py - all 23 handlers","error_responses.py - error factory","validation.py - input validation","logger_config.py - structured logging"], "existing_external": ["mcp@1.0.0+","pydantic@2.0.0+"], "new_external": ["flask==3.0.0","python-dotenv==1.0.0"], "new_internal": [] }, "architecture_context": "HTTP adapter layer between ChatGPT and MCP tools. Transport layer. Receives JSON-RPC 2.0→validates→calls tool_handlers→returns JSON. No business logic changes. Follows existing error and validation patterns." }, "4_key_features": { "primary_features": ["POST /mcp endpoint accepts JSON-RPC 2.0 and routes to tool_handlers dispatcher", "GET /tools returns array of 23 tools with schemas for ChatGPT discovery", "GET /health returns status/timestamp/version for Railway health checks", "Proper error handling: protocol errors return JSON-RPC errors, tool errors wrapped in JSON", "Flask binds to PORT env variable for Railway compatibility"], "secondary_features": ["Request logging with tool_name, params_keys, execution_time", "Response formatting: tool output to JSON in {result} wrapper", "Tool discovery caching at startup to prevent repeated parsing"], "edge_case_handling": ["Unknown tool: JSON-RPC -32601 'Method not found'", "Missing params: JSON-RPC -32602 'Invalid params'", "Timeout >60s: {error: 'Tool execution timeout'}", "Exception: caught and formatted as {error: message}"], "configuration_options": ["PORT env variable","FLASK_ENV (development/production)","MCP_SERVER_PATH (if reusing server)"] }, "5_task_id_system": [ "SETUP-001: Add flask==3.0.0, python-dotenv==1.0.0 to requirements.txt and verify no version conflicts with existing mcp and pydantic packages", "SETUP-002: Create http_server.py with Flask application factory, error handlers for 404/500, graceful SIGTERM shutdown, PORT binding for Railway", "SETUP-003: Create .env.railway.example with PORT, FLASK_ENV, MCP_PROJECT_PATH variables clearly documented for Railway deployment", "HTTP-001: Implement GET /health endpoint returning {status: operational, timestamp: ISO8601, version: 1.0.0} JSON with 200 status", "HTTP-002: Implement GET /tools endpoint returning JSON array of all 23 tools with name, description, inputSchema, caching at startup", "HTTP-003: Implement POST /mcp endpoint accepting JSON-RPC 2.0 request {jsonrpc: 2.0, id, method, params} with required field validation", "HTTP-004: Create http_handlers.py module with route_tool_call(method, params) that looks up tool in TOOL_HANDLERS dict, handles KeyError", "HTTP-005: Implement parameter validation in HTTP layer verifying params dict type, required fields present, basic type checking", "HTTP-006: Implement tool execution wrapper calling tool_handlers[name](params), catching exceptions, converting responses to JSON", "HTTP-007: Implement comprehensive JSON-RPC error handling for protocol errors (-32600-32603) and tool errors (-32000) with proper codes", "HTTP-008: Add structured request logging to /mcp endpoint showing tool_name, param_keys, execution_time, status_code", "HTTP-009: Create Procfile with single line 'web: gunicorn http_server:app' for Railway deployment", "HTTP-010: Add CORS headers (Access-Control-Allow-Origin: *) for development, document v2 will restrict to ChatGPT domain", "TEST-001: Write test_health_endpoint() verifying GET /health returns 200 with required JSON fields and <50ms response", "TEST-002: Write test_tools_list() verifying GET /tools returns 200 with array of exactly 23 tools with schemas", "TEST-003: Write test_valid_tool_call() calling list_templates via POST /mcp, verifying correct JSON-RPC response structure", "TEST-004: Write test_unknown_tool() calling POST /mcp with invalid method, verifying -32601 JSON-RPC error returned", "TEST-005: Write test_missing_params() calling POST /mcp without required project_path, verifying -32602 error", "TEST-006: Write test_malformed_json() sending invalid JSON to /mcp, verifying -32700 parse error returned", "TEST-007: Write test_tool_exception() simulating tool exception, verifying wrapped in {error, code:-32000} response", "TEST-008: Write test_concurrent_requests() sending 20 simultaneous requests, verifying all complete without cross-talk or race conditions", "DEPLOY-001: Create Railway.app project, configure PORT binding to accept dynamic port, verify application starts", "DEPLOY-002: Push code to Railway-connected repo, verify Procfile detected and gunicorn starts with correct Python", "DEPLOY-003: Test deployed /health and /tools endpoints with curl, verify responses match local execution", "DEPLOY-004: Test full tool invocation on Railway calling /mcp with list_templates, verify response matches local" ], "6_implementation_phases": [ {"title": "Phase 1: Setup","purpose": "Scaffold Flask and dependencies","complexity": "low","effort_level": 2,"tasks": ["SETUP-001","SETUP-002","SETUP-003"],"completion_criteria": "requirements.txt updated, http_server.py created, env example documented, imports work"}, {"title": "Phase 2: Endpoints","purpose": "Implement all HTTP endpoints","complexity": "high","effort_level": 4,"tasks": ["HTTP-001","HTTP-002","HTTP-003","HTTP-004","HTTP-005","HTTP-006","HTTP-009"],"completion_criteria": "All endpoints functional, routing works, JSON-RPC correct, local curl tests pass"}, {"title": "Phase 3: Errors","purpose": "Error handling and logging","complexity": "medium","effort_level": 3,"tasks": ["HTTP-007","HTTP-008","HTTP-010"],"completion_criteria": "All error codes correct, logging shows invocations, errors properly masked"}, {"title": "Phase 4: Tests","purpose": "Comprehensive test suite","complexity": "high","effort_level": 3,"tasks": ["TEST-001","TEST-002","TEST-003","TEST-004","TEST-005","TEST-006","TEST-007","TEST-008"],"completion_criteria": "All tests pass, coverage >85%, edge cases verified, concurrency OK"}, {"title": "Phase 5: Deploy","purpose": "Railway deployment verification","complexity": "medium","effort_level": 2,"tasks": ["DEPLOY-001","DEPLOY-002","DEPLOY-003","DEPLOY-004"],"completion_criteria": "Deployed to Railway, endpoints respond, tools work, HTTPS accessible"} ], "7_testing_strategy": { "unit_tests": {"scope": "Individual HTTP handlers in isolation","coverage_target": "85%+","tests": ["test_health_format","test_tools_completeness","test_json_rpc_validation","test_error_response_format"]}, "integration_tests": {"scope": "Full request flow HTTP to tool","focus": "JSON-RPC protocol, tool integration, error propagation","tests": ["test_list_templates_via_http","test_invalid_tool_error","test_tool_with_params"]}, "edge_case_scenarios": [ {"scenario": "Unknown tool","setup": "POST /mcp method=fake_tool","expected_behavior": "-32601 error","verification": "code:-32601, message has 'Method not found'","error_handling": "JSON-RPC error"}, {"scenario": "Missing params","setup": "POST /mcp method=analyze_project_for_planning params={}","expected_behavior": "-32602 error","verification": "code:-32602, mentions missing project_path","error_handling": "JSON-RPC error"}, {"scenario": "Malformed JSON","setup": "POST /mcp body='{invalid'","expected_behavior": "-32700 error","verification": "code:-32700","error_handling": "JSON-RPC error"}, {"scenario": "Timeout","setup": "Long-running inventory >60s","expected_behavior": "Timeout error after 60s","verification": "Response has timeout message","error_handling": "Graceful timeout"}, {"scenario": "Tool exception","setup": "Invalid project_path causing error","expected_behavior": "Exception caught and formatted","verification": "error field with message","error_handling": "Caught and formatted"}, {"scenario": "Concurrent","setup": "20 simultaneous requests","expected_behavior": "All complete without cross-talk","verification": "Each has unique id, appropriate results","error_handling": "Flask handles concurrency"}, {"scenario": "Large output","setup": "Inventory on massive project >1MB","expected_behavior": "Full result returned","verification": "Size matches expected","error_handling": "No truncation"}, {"scenario": "Missing jsonrpc","setup": "POST /mcp {id:1, method:list_templates}","expected_behavior": "-32600 Invalid Request","verification": "code:-32600","error_handling": "JSON-RPC error"}, {"scenario": "/health load","setup": "100 req/sec to /health","expected_behavior": "All 200 within 50ms","verification": "P95 <50ms","error_handling": "No error"}, {"scenario": "Shutdown","setup": "SIGTERM during request","expected_behavior": "In-flight completes, new rejected","verification": "Get response, then 503","error_handling": "Flask shutdown"} ] }, "8_success_criteria": { "functional": [ {"requirement": "Endpoints operational","metric": "All return 200","target": "/health, /tools, /mcp return valid JSON","validation": "Tests pass"}, {"requirement": "Tool invocation","metric": "Callable via HTTP","target": "Same result as direct","validation": "test_list_templates_via_http"}, {"requirement": "JSON-RPC compliance","metric": "Protocol adherence","target": "Correct response structure","validation": "Validation tests"}, {"requirement": "Error handling","metric": "Appropriate codes","target": "-32601/-32602/-32700/-32000","validation": "Error tests"} ], "quality": [ {"requirement": "Code style","metric": "pylint passes","target": "exit 0","validation": "pylint check"}, {"requirement": "Coverage","metric": ">85%","target": "pytest --cov","validation": "Coverage report"}, {"requirement": "Type safety","metric": "mypy passes","target": "exit 0","validation": "mypy check"}, {"requirement": "Documentation","metric": "Docstrings present","target": "All functions","validation": "Code review"} ], "performance": [ {"requirement": "/health speed","metric": "P95 <50ms","target": "Load 100 req","validation": "Performance test"}, {"requirement": "/tools speed","metric": "P95 <100ms","target": "Load 50 req","validation": "Performance test"}, {"requirement": "Tool exec","metric": "Simple P95 <1s","target": "list_templates","validation": "Performance test"} ], "security": [ {"requirement": "No traversal","metric": "Paths rejected","target": "../../etc/passwd denied","validation": "Security test"}, {"requirement": "Masking","metric": "Secrets masked","target": "No raw API keys","validation": "config_inventory test"}, {"requirement": "Validation","metric": "Invalid rejected","target": "Non-dict, missing fields","validation": "Validation tests"} ] }, "9_implementation_checklist": { "pre": ["☐ Review plan","☐ Verify ChatGPT specs","☐ Test tool_handlers","☐ Dev environment"], "phase_1": ["☐ SETUP-001","☐ SETUP-002","☐ SETUP-003"], "phase_2": ["☐ HTTP-001","☐ HTTP-002","☐ HTTP-003","☐ HTTP-004","☐ HTTP-005","☐ HTTP-006","☐ HTTP-009"], "phase_3": ["☐ HTTP-007","☐ HTTP-008","☐ HTTP-010"], "phase_4": ["☐ TEST-001","☐ TEST-002","☐ TEST-003","☐ TEST-004","☐ TEST-005","☐ TEST-006","☐ TEST-007","☐ TEST-008"], "phase_5": ["☐ DEPLOY-001","☐ DEPLOY-002","☐ DEPLOY-003","☐ DEPLOY-004"], "final": ["☐ All tests pass","☐ Coverage >85%","☐ Type check pass","☐ Lint pass","☐ README update","☐ CLAUDE.md update","☐ Changelog entry","☐ Code review","☐ Railway smoke tests","☐ ChatGPT verify"] }, "metadata": {"plan_version": "1.0.0","created_at": "2025-10-16T04:20:00Z","sections": 10,"total_tasks": 24,"phases": 5,"estimated_effort": "5-7 days","status": "ready_for_implementation"} }