{
  "markdown": "# Coding Guides MCP Server\n\nA Model Context Protocol (MCP) server that provides access to coding guides and best practices for AI assistants like Claude and GitHub Copilot.\n\n## What is this?\n\nThis MCP server exposes coding guidelines and style guides as resources that can be accessed by MCP clients. It's designed to extend or replace `AGENTS.md` files by providing a structured way to serve coding practices and guidelines to AI assistants during development.\n\n## Features\n\n- **Resource-based API**: Exposes coding guides through MCP resources\n- **GitHub integration**: Loads guides from GitHub repositories over the web\n- **Automatic caching**: Caches downloaded guides locally for offline access\n- **Fallback support**: Uses local cache or directory when network is unavailable\n- **Simple file-based storage**: Guides can be stored as Markdown files locally\n- **Official MCP SDK**: Built on the Python `mcp` SDK (`MCPServer`, formerly FastMCP)\n- **Easy integration**: Works with any MCP-compatible client (Claude Desktop, Cline, etc.)\n\n## Available Resources\n\n- `guides://list` - Lists all available coding guides\n- `guides://{guide_name}` - Retrieves the content of a specific guide (e.g., `guides://python.md`)\n\n## Installation\n\n### From Source\n\n```bash\n# Clone the repository\ngit clone https://github.com/delian/codeguide-mcp.git\ncd codeguide-mcp\n\n# Install with uv (recommended)\nuv sync\n\n# Or with pip\npip install -e .\n```\n\n### With Docker\n\n```bash\ndocker build -t codeguide-mcp .\ndocker run -i codeguide-mcp\n```\n\n### In VS Code\n\n[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_codeguide--mcp-0098FF?logo=githubcopilot&logoColor=white)](https://vscode.dev/redirect/mcp/install?name=codeguide-mcp&config=%7B%22command%22%3A%22docker%22%2C%22args%22%3A%5B%22run%22%2C%22-i%22%2C%22--rm%22%2C%22delian%2Fcodeguide-mcp%22%5D%7D)\n\nOr search for `codeguide-mcp` in the Extensions view MCP servers list (type `@mcp` in the Extensions search bar), or add it manually to `.vscode/mcp.json`:\n\n```json\n{\n  \"servers\": {\n    \"codeguide-mcp\": {\n      \"command\": \"docker\",\n      \"args\": [\"run\", \"-i\", \"--rm\", \"delian/codeguide-mcp\"]\n    }\n  }\n}\n```\n\n## Configuration\n\nConfigure the server by creating a `config.toml` file or setting environment variables:\n\n### GitHub Configuration (Recommended)\n\nTo load guides from a GitHub repository:\n\n```toml\ngithub_repo = \"owner/repository\"  # e.g., \"delian/codeguide-mcp\"\ngithub_path = \"guides\"            # Path to guides directory in repo\ngithub_branch = \"main\"            # Branch to fetch from\n  cache_dir = \".guides-cache\"       # Local cache directory\nlog_level = \"INFO\"\n```\n\n### Local Directory Configuration\n\nTo use local guides only:\n\n```toml\nguides_dir = \"guides\"\nlog_level = \"INFO\"\n```\n\n### Environment Variables\n\n- `GUIDES_GITHUB_REPO` - GitHub repository (format: `owner/repo`)\n- `GUIDES_GITHUB_PATH` - Path to guides directory in repository (default: `guides`)\n- `GUIDES_GITHUB_BRANCH` - Branch to fetch from (default: `main`)\n- `GUIDES_CACHE_DIR` - Local cache directory (default: `.guides-cache`)\n- `GUIDES_DIR` - Local directory containing guide files (default: `guides`)\n- `GUIDES_LOG_LEVEL` - Logging level (default: `INFO`)\n\nTransport (see [Remote deployment](#remote-deployment-google-cloud-run)):\n\n- `GUIDES_TRANSPORT` - `stdio`, `streamable-http`, or `auto` (default: `auto` — HTTP when a `PORT` env var is present, stdio otherwise)\n- `PORT` - Port to listen on in HTTP mode; takes precedence over `GUIDES_PORT` (Cloud Run injects this)\n- `GUIDES_HOST` - Bind address in HTTP mode (default: `0.0.0.0`)\n- `GUIDES_HTTP_PATH` - MCP endpoint path (default: `/mcp`)\n- `GUIDES_STATELESS_HTTP` - Handle each request independently (default: `true`; required when replicas autoscale)\n- `GUIDES_ALLOWED_HOSTS` - Host header allowlist enabling DNS-rebinding protection (default: empty = no Host validation)\n\n### Behavior\n\n1. **Network available + GitHub configured**: Fetches guides from GitHub and caches them locally\n2. **Network unavailable**: Uses local cache if available\n3. **No cache available**: Falls back to local `guides_dir` if configured\n\n## Remote deployment (Google Cloud Run)\n\nThe same image serves both transports: it speaks stdio over a pipe by default,\nand switches to Streamable HTTP when a `PORT` env var is present — which Cloud Run\nalways injects. No separate image or entrypoint is needed.\n\n### 1. Publish the image\n\n```bash\ndocker build -t delian/codeguide-mcp:0.1.0 -t delian/codeguide-mcp:latest .\ndocker push delian/codeguide-mcp:0.1.0\ndocker push delian/codeguide-mcp:latest\n```\n\n### 2. Deploy\n\n```bash\ngcloud run deploy codeguide-mcp \\\n  --image=docker.io/delian/codeguide-mcp:0.1.0 \\\n  --region=europe-west1 \\\n  --allow-unauthenticated \\\n  --port=8080 \\\n  --set-env-vars=GUIDES_TRANSPORT=streamable-http,GUIDES_GITHUB_REPO= \\\n  --memory=512Mi --cpu=1 \\\n  --min-instances=0 --max-instances=4 --concurrency=40\n```\n\n`GUIDES_GITHUB_REPO=` (empty) makes the service serve the guides baked into the\nimage. Leaving GitHub enabled adds a network round-trip per guide and runs into\nthe unauthenticated GitHub API limit of 60 requests/hour per egress IP, after\nwhich the server silently falls back to those same baked-in files anyway.\n\nThe MCP endpoint is then `https://<service-url>/mcp`:\n\n```bash\ngcloud run services describe codeguide-mcp --region=europe-west1 \\\n  --format='value(status.url)'\n```\n\nCloud Run answers on two hostnames for the same service — the\n`SERVICE-PROJECTNUMBER.REGION.run.app` form printed by `gcloud run deploy`, and\nthe older `SERVICE-HASH-REGIONCODE.a.run.app` form that `status.url` reports.\nBoth are equivalent; either works in a client config.\n\n### 3. Point clients at it\n\nSee [Connecting to a remote server](#connecting-to-a-remote-server) below for the\nper-client configuration.\n\n### Pulling from Docker Hub\n\nCloud Run deploys public Docker Hub images directly, but caches them for only an\nhour and re-pulls anonymously afterwards, so a scale-up can hit Docker Hub's\nanonymous pull limits and fail to start instances. For anything beyond casual\nuse, mirror through an Artifact Registry remote repository:\n\n```bash\ngcloud artifacts repositories create dockerhub \\\n  --repository-format=docker --location=europe-west1 \\\n  --mode=remote-repository --remote-docker-repo=DOCKER-HUB\n\ngcloud run deploy codeguide-mcp \\\n  --image=europe-west1-docker.pkg.dev/PROJECT_ID/dockerhub/delian/codeguide-mcp:0.1.0 \\\n  ...\n```\n\n### Notes on running it publicly\n\n- `--allow-unauthenticated` makes the endpoint world-callable. The server is\n  read-only, but the `clear_cache` prompt is reachable by any caller and drops\n  the in-memory caches, and traffic drives autoscaling cost — keep\n  `--max-instances` capped. To restrict access, omit the flag and have clients\n  send an identity token, or front the service with Cloud Armor / API Gateway.\n- `GUIDES_STATELESS_HTTP` must stay `true` unless you also enable session\n  affinity, since Cloud Run may route a session's requests to different instances.\n- `GET /` returns 404 by design; only `/mcp` is served. Cloud Run's default\n  startup probe is a TCP check on `$PORT`, so this is fine — don't configure an\n  HTTP health check on `/`.\n- Set `GUIDES_ALLOWED_HOSTS` to your service hostname to enable Host-header\n  validation if you expose the service under a custom domain.\n\n## Publishing to the MCP Registry\n\nThe MCP servers list in the VS Code Extensions view (type `@mcp` in the search\nbar) is fed by the GitHub MCP Registry, which ingests from the official\n[MCP Registry](https://registry.modelcontextprotocol.io). Publishing there is\ntherefore how this server becomes discoverable in VS Code — no VS Code extension\nof its own is required.\n\n[`server.json`](server.json) holds the registry metadata: the Docker image for\nclients that want to run it locally, and the hosted URL for clients that would\nrather not. Ownership of the image is proven by the\n`io.modelcontextprotocol.server.name` label in the [Dockerfile](Dockerfile),\nwhose value **must** equal `.name` in `server.json`.\n\nAuthenticate once (an interactive device-code flow), then run the publish script:\n\n```bash\nmcp-publisher login github     # namespace io.github.<your-username>/*\ntools/publish.sh\n```\n\n[`tools/publish.sh`](tools/publish.sh) does the whole release: it checks the\nrequired tooling and Docker login, verifies that `server.json` and\n`pyproject.toml` agree on the version and that the Dockerfile label matches the\nserver name, builds and pushes `:VERSION` and `:latest`, validates `server.json`\nagainst the live registry, publishes, then reads the entry back to confirm.\n\n```bash\ntools/publish.sh --dry-run          # everything except push and publish\ntools/publish.sh --version 0.2.0    # bump server.json + pyproject + image tag, then release\ntools/publish.sh --skip-build       # reuse images already on Docker Hub\n```\n\nInstall `mcp-publisher` from the\n[registry quickstart](https://modelcontextprotocol.io/registry/quickstart) if\nyou do not have it. After publishing, inclusion in GitHub's curated list may\nneed a request to `partnerships@github.com`.\n\n## Adding Guides\n\n### Using GitHub (Recommended)\n\nIf you've configured `github_repo`, simply add Markdown files to the specified directory in your GitHub repository. The server will automatically fetch and cache them.\n\n### Using Local Directory\n\nAdd Markdown files to the `guides/` directory. Each file will be automatically available as a resource.\n\nExample:\n```bash\necho \"# Python Style Guide\\n\\nUse PEP 8...\" > guides/python.md\n```\n\n## Usage with MCP Clients\n\nThe server can be consumed two ways:\n\n| Mode | Transport | How the client reaches it |\n| --- | --- | --- |\n| **Local** | stdio | Client spawns `python main.py` or `docker run -i` and talks over a pipe |\n| **Remote** | Streamable HTTP | Client makes HTTPS requests to a hosted `…/mcp` URL |\n\nLocal mode needs no network and no hosting; remote mode lets a team share one\ndeployment and keeps the guides identical for everyone.\n\n### Connecting to a remote server\n\nA deployed instance exposes its MCP endpoint at `/mcp`. The snippets below use the\nreference deployment:\n\n```\nhttps://codeguide-mcp-86057491046.europe-west1.run.app/mcp\n```\n\nIt is public and needs no credentials. Substitute your own URL if you run the\nservice yourself — see [Remote deployment](#remote-deployment-google-cloud-run).\n\n**VS Code** — `.vscode/mcp.json` for one workspace, or your user `mcp.json` for\nevery workspace:\n\n```json\n{\n  \"servers\": {\n    \"codeguide-mcp\": {\n      \"type\": \"http\",\n      \"url\": \"https://codeguide-mcp-86057491046.europe-west1.run.app/mcp\"\n    }\n  }\n}\n```\n\n**Claude Code**:\n\n```bash\nclaude mcp add --transport http codeguide-mcp \\\n  https://codeguide-mcp-86057491046.europe-west1.run.app/mcp\n```\n\n**Cursor** — `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (per project):\n\n```json\n{\n  \"mcpServers\": {\n    \"codeguide-mcp\": {\n      \"url\": \"https://codeguide-mcp-86057491046.europe-west1.run.app/mcp\"\n    }\n  }\n}\n```\n\n**Claude Desktop** — add it as a custom connector in Settings, or bridge the\nremote endpoint into a stdio client with\n[`mcp-remote`](https://www.npmjs.com/package/mcp-remote):\n\n```json\n{\n  \"mcpServers\": {\n    \"codeguide-mcp\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"mcp-remote\", \"https://codeguide-mcp-86057491046.europe-west1.run.app/mcp\"]\n    }\n  }\n}\n```\n\n**Any client** that speaks Streamable HTTP works — point it at the `/mcp` URL.\nFor servers behind authentication, pass a token with\n`--header \"Authorization: Bearer $(gcloud auth print-identity-token)\"`\n(Claude Code) or the client's equivalent `headers` block.\n\n### Verifying a remote endpoint\n\nA single `curl` confirms a deployment is live and public:\n\n```bash\ncurl -s -X POST https://codeguide-mcp-86057491046.europe-west1.run.app/mcp \\\n  -H 'Content-Type: application/json' \\\n  -H 'Accept: application/json, text/event-stream' \\\n  -d '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"initialize\",\"params\":{\n       \"protocolVersion\":\"2025-06-18\",\"capabilities\":{},\n       \"clientInfo\":{\"name\":\"curl\",\"version\":\"1\"}}}'\n```\n\nA healthy server replies with an SSE `event: message` frame containing its\ncapabilities and instructions. Note that `GET /` returns 404 by design — only\n`/mcp` is served.\n\nTo exercise every resource, tool, and prompt over HTTP instead:\n\n```bash\nuv run python verify_server.py --http https://codeguide-mcp-86057491046.europe-west1.run.app/mcp\n```\n\n### Local usage\n\n#### Claude Desktop\n\nAdd to your `mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"coding-guides\": {\n      \"command\": \"python\",\n      \"args\": [\"-m\", \"main\"]\n    }\n  }\n}\n```\n\nor\n\n```json\n{\n  \"mcpServers\": {\n    \"coding-guides\": {\n      \"command\": \"docker\",\n      \"args\": [\"run\", \"--rm\", \"-i\", \"docker.io/delian/codeguide-mcp\"]\n    }\n  }\n}\n```\n\n### Other MCP Clients\n\nRun the server and connect via stdio:\n\n```bash\npython main.py\n```\n\n## Development\n\n```bash\n# Install development dependencies\nuv pip install -e \".[dev]\"\n\n# Run pre-commit hooks\npre-commit install\npre-commit run --all-files\n\n# Run the server\npython main.py\n```\n\n## License\n\nMIT\n\n## Contributing\n\nContributions welcome! Please open an issue or pull request.\n",
  "bytes": 13127,
  "sha": "aaa56547d591b433366c7c58a4a65757f9546d9ce8d23492d11d0d2bc33d9618",
  "repo_slug": "delian/codeguide-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_delian_codeguide_mcp_eb88ab70/readme"
}