{"id":29878243,"url":"https://github.com/rameshsunkara/go-mcp-example","last_synced_at":"2025-08-03T10:04:13.241Z","repository":{"id":306866603,"uuid":"1027446294","full_name":"rameshsunkara/go-mcp-example","owner":"rameshsunkara","description":"An idiomatic, minimal example of building an MCP (Model Context Protocol) server in Go, complete with essential tooling for developing Go-based microservices.","archived":false,"fork":false,"pushed_at":"2025-07-28T04:12:40.000Z","size":60,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-07-28T06:18:14.490Z","etag":null,"topics":["example","go-mcp","golang","mcp","mcp-server","modelcontextprotocol"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rameshsunkara.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-28T02:59:51.000Z","updated_at":"2025-07-28T04:12:43.000Z","dependencies_parsed_at":"2025-07-28T06:28:34.762Z","dependency_job_id":null,"html_url":"https://github.com/rameshsunkara/go-mcp-example","commit_stats":null,"previous_names":["rameshsunkara/go-mcp-example"],"tags_count":null,"template":false,"template_full_name":"rameshsunkara/go-rest-api-example","purl":"pkg:github/rameshsunkara/go-mcp-example","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rameshsunkara%2Fgo-mcp-example","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rameshsunkara%2Fgo-mcp-example/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rameshsunkara%2Fgo-mcp-example/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rameshsunkara%2Fgo-mcp-example/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rameshsunkara","download_url":"https://codeload.github.com/rameshsunkara/go-mcp-example/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rameshsunkara%2Fgo-mcp-example/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":268003447,"owners_count":24179290,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-31T02:00:08.723Z","response_time":66,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["example","go-mcp","golang","mcp","mcp-server","modelcontextprotocol"],"created_at":"2025-07-31T07:01:30.959Z","updated_at":"2025-07-31T07:03:32.482Z","avatar_url":"https://github.com/rameshsunkara.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![MCP Server Build](https://github.com/rameshsunkara/go-mcp-example/actions/workflows/cibuild.yml/badge.svg)](https://github.com/rameshsunkara/go-mcp-example/actions/workflows/cibuild.yml)\n[![Go Report Card](https://goreportcard.com/badge/github.com/rameshsunkara/go-mcp-example)](https://goreportcard.com/report/github.com/rameshsunkara/go-mcp-example)\n\n# Go MCP Server Example\n\nA robust Model Context Protocol (MCP) server implementation in Go, featuring analytics reporting tools with idiomatic Go architecture, comprehensive error handling, and enterprise-grade configurability.\n\n## Overview\n\nThis project demonstrates a well-structured MCP server that provides analytics reporting capabilities by interfacing with external APIs. It showcases modern Go development practices including dependency injection, structured logging, configuration management, and comprehensive error handling.\n\n## Features\n\n### MCP Protocol Features\n\n1. **Tools**: Analytics report fetching with configurable parameters\n2. **Resources**: Extensible resource management system  \n3. **Prompts**: Interactive prompt system for enhanced user experience\n4. **Error Handling**: Consistent error responses with proper MCP error formatting\n\n### Architecture Features\n\n1. **Idiomatic Go Structure**: Clean separation of concerns with dedicated packages\n2. **Dependency Injection**: Testable components with injectable dependencies\n3. **Configuration Management**: Environment-based configuration with validation\n4. **Structured Logging**: Context-aware logging with slog\n5. **Type Safety**: Generated models from OpenAPI specifications\n6. **Security**: Secure handling of API keys and sensitive configuration\n\n### Development Features\n\n1. **OpenAPI Integration**: Auto-generated models from API specifications\n2. **Testable HTTP Client**: Injectable HTTP client interface for easy mocking\n3. **Comprehensive Error Handling**: All errors returned as MCP-compatible responses\n4. **Docker Support**: Containerized deployment with multi-stage builds\n5. **VS Code Integration**: Configured for seamless MCP server development\n\n## Project Structure\n\n```text\ngo-mcp-example/\n├── main.go                        # Entry point and MCP server setup\n├── config/                        # Configuration management\n├── models/                        # Data types and API models\n├── tools/                         # MCP tools implementation\n├── prompts/                       # Interactive prompts\n├── resources/                     # MCP resources\n├── docs/                          # Documentation and setup guides\n│   ├── claude-desktop/            # Claude Desktop configuration\n│   └── vscode/                    # VS Code configuration\n├── .vscode/                       # VS Code project settings\n├── .env.example                   # Environment template\n├── Dockerfile                     # Container configuration\n├── Makefile                       # Development commands\n├── openapi.yaml                   # API specification\n└── ...                           # Other config files\n```\n\n## Architecture Flow\n\n```mermaid\nflowchart TD\n    A[MCP Client] --\u003e|JSON-RPC| B[MCP Server]\n    B --\u003e C{Request Type}\n    C --\u003e|Tool Call| D[Tools Package]\n    C --\u003e|Resource| E[Resources Package]\n    C --\u003e|Prompt| F[Prompts Package]\n    \n    D --\u003e G[Reports Tool]\n    G --\u003e H[API Client]\n    H --\u003e I[External API]\n    \n    G --\u003e J[Config]\n    G --\u003e K[Logger]\n    \n    L[Models] --\u003e G\n    L --\u003e H\n```\n\nThe MCP server handles three types of operations:\n\n1. **Tools**: Execute analytics report fetching with configurable parameters\n2. **Resources**: Provide access to static or dynamic resources\n3. **Prompts**: Handle interactive prompts for enhanced user experience\n\n## Quick Start\n\n### Prerequisites\n\n- Go 1.24+\n- US Data Analytics Program API key ([Get your API key here](https://open.gsa.gov/api/dap/#authentication))\n- Make (optional, for convenience commands)\n- Docker (optional, for containerized deployment)\n\n### Running the MCP Server\n\n1. **Clone and setup**:\n\n   ```bash\n   git clone https://github.com/rameshsunkara/go-mcp-example.git\n   cd go-mcp-example\n   cp .env.example .env  # Configure your API settings\n   ```\n\n   **Important**: Edit the `.env` file and add your API key:\n\n   ```bash\n   API_KEY=your-actual-api-key-here\n   ```\n\n   Get your API key from: \u003chttps://open.gsa.gov/api/dap/#authentication\u003e\n\n2. **Install dependencies**:\n\n   ```bash\n   go mod download\n   ```\n\n3. **Run the server**:\n\n   ```bash\n   # Via stdio (default MCP transport)\n   make run\n   # OR: go run main.go\n   \n   # Via HTTP (for debugging)\n   make run-http\n   # OR: go run main.go --http localhost:8080\n   ```\n\n## Client Integration\n\nThis project includes pre-configured setups for both VS Code and Claude Desktop. Choose your preferred client:\n\n### VS Code Setup\n\n1. **Build the executable**: `make build`\n2. **Copy configurations**: `cp docs/vscode/* .vscode/`\n3. **Install MCP Extension**: Install the official MCP extension for VS Code\n\nFor detailed instructions, see the [VS Code Setup Guide](docs/vscode/README.md).\n\n### Claude Desktop Setup\n\n1. **Build the binary**: `make build`\n2. **Copy configuration**: Copy `docs/claude-desktop/claude-desktop-config.json` to your Claude Desktop config directory\n3. **Update paths and API_KEY** in the configuration file\n4. **Restart Claude Desktop**\n\nFor detailed instructions, see the [Claude Desktop Setup Guide](docs/claude-desktop/README.md).\n\n### Configuration\n\nConfigure via environment variables, `.env` file, or VS Code's `.vscode/mcp.json`:\n\n```bash\n# API Configuration\nAPI_BASE_URL=https://api.gsa.gov/analytics/dap/v2\nAPI_KEY=your-secret-api-key-here  # Get your API key: https://open.gsa.gov/api/dap/#authentication\n\n# Logging Configuration  \nLOG_LEVEL=info                    # debug, info, warn, error\nLOG_FORMAT=json                   # json, text\n\n# Server Configuration (optional)\nHTTP_ADDR=localhost:8080          # Enable HTTP transport for debugging\n```\n\n### Available Tools\n\n#### get_report - Analytics Report Fetching\n\nFetches analytics reports from the [Digital Analytics Program (DAP) API](https://open.gsa.gov/api/dap/#reports) for U.S. federal government websites.\n\n**Parameters:**\n\n- `report_name` (required): The type of report to fetch\n- `limit` (optional): Maximum records (1-10000, default 1000)\n- `page` (optional): Page number for pagination (default 1)\n- `after`/`before` (optional): Date filters (YYYY-MM-DD format)\n\n**Common Report Types:**\n\n| Report Type | Description |\n|-------------|-------------|\n| `traffic` | Traffic volume and trends over time |\n| `top-pages` | Most visited pages and metrics |\n| `devices` | Device usage (desktop, mobile, tablet) |\n| `browsers` | Browser usage statistics |\n| `countries` | Geographic breakdown by country |\n| `realtime` | Real-time active users |\n\n*See tool description for all 12+ available report types.*\n\n**Example Usage:**\n\n```bash\nget_report(\"traffic\")                                    # Basic usage\nget_report(\"top-pages\", limit=50)                      # With limit\nget_report(\"browsers\", after=\"2024-01-01\", before=\"2024-01-31\")  # Date range\n```\n\n## Troubleshooting\n\n### Common Issues\n\n#### Empty or No Results from API\n\nThe Digital Analytics Program (DAP) API may sometimes return empty results or no data for certain queries. This is a known limitation of the current API endpoint. Common scenarios include:\n\n- **Recent dates**: Very recent data (last 24-48 hours) may not be available yet\n- **Specific filters**: Certain combinations of filters may not have data\n- **Low-traffic periods**: Some reports may be empty during low-traffic periods\n- **API maintenance**: The API may be temporarily unavailable or returning limited data\n\n**Workarounds:**\n\n- Try querying data from a few days ago instead of today\n- Use broader date ranges to increase the likelihood of finding data\n- Check different report types to see if the issue is report-specific\n- Try removing optional filters to get broader results\n\n**Future Plans:**\n\nI am aware of these API reliability issues and are evaluating more stable analytics APIs to provide better data consistency and availability. A migration to a more reliable data source is planned for a future release.\n\n### Development Commands\n\nThe Makefile provides convenient development commands:\n\n```bash\n# Building and Running\nmake build                         # Build the MCP server binary\nmake run                           # Run the server via stdio (default MCP transport)\nmake run-http                      # Run the server via HTTP (for debugging)\n\n# Testing and Quality\nmake test                          # Run tests with coverage\nmake coverage                      # Generate and display coverage report\nmake lint                          # Run the linter\nmake lint-fix                      # Run the linter and fix issues\nmake format                        # Format Go code\nmake tidy                          # Tidy Go modules\nmake ci-local                      # Run full CI pipeline locally\n\n# Docker\nmake docker-build                  # Build Docker image\nmake docker-run                    # Run containerized server\nmake docker-clean                  # Clean Docker resources\n```\n\n### Docker Deployment\n\n```bash\n# Build Docker image\nmake docker-build\n\n# Run containerized server\nmake docker-run\n```\n\n## Technology Stack\n\n1. **MCP Protocol**: [Model Context Protocol Go SDK](https://github.com/modelcontextprotocol/go-sdk)\n2. **Logging**: [slog](https://pkg.go.dev/log/slog) - Structured logging\n3. **HTTP Client**: Standard `net/http` with dependency injection\n4. **Configuration**: Environment variables with validation\n5. **Container**: [Docker](https://www.docker.com/) with multi-stage builds\n\n## Roadmap\n\n- **Enhanced Analytics**: Add support for more analytics endpoints and data sources\n- **Authentication**: Add support for multiple authentication mechanisms\n- **Testing**: Comprehensive unit and integration test coverage\n\n## Contributing\n\n- Feel free to open Pull Requests with improvements\n- Create issues for bugs or feature requests  \n- Suggestions for architectural improvements are welcome\n\n### What This Is\n\n- A production-ready MCP server template\n- A showcase of modern Go development practices and patterns\n- A foundation for building custom MCP tools and integrations\n- A reference implementation for MCP protocol handling in Go\n\n### What This Is Not\n\n- A one-size-fits-all solution (customize it for your specific needs)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frameshsunkara%2Fgo-mcp-example","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frameshsunkara%2Fgo-mcp-example","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frameshsunkara%2Fgo-mcp-example/lists"}