Coding Guides
Coding guidelines and best-practice guides for 130+ languages, frameworks, and tools.
Open source Repository Open in the app JSON README (API)
About
Coding guidelines and best-practice guides for 130+ languages, frameworks, and tools.
Details
- Kind
- MCP servers
- Topic
- No topic detected
- Publisher
- delian
- Origin
- official
- Category
- ferramentas
- Transport
- http
- Version
- 0.1.0
- Open pull requests
- 3
- Last push
- 2026-08-19T16:59:56Z
- Repository state
- ativo
- Language
- Python
- Added
- 2026-08-29 03:02:41
- Updated
- 2026-08-29 03:02:41
- Origin id
io.github.delian/codeguide-mcp
README
# Coding Guides MCP Server
A Model Context Protocol (MCP) server that provides access to coding guides and best practices for AI assistants like Claude and GitHub Copilot.
## What is this?
This 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.
## Features
- **Resource-based API**: Exposes coding guides through MCP resources
- **GitHub integration**: Loads guides from GitHub repositories over the web
- **Automatic caching**: Caches downloaded guides locally for offline access
- **Fallback support**: Uses local cache or directory when network is unavailable
- **Simple file-based storage**: Guides can be stored as Markdown files locally
- **Official MCP SDK**: Built on the Python `mcp` SDK (`MCPServer`, formerly FastMCP)
- **Easy integration**: Works with any MCP-compatible client (Claude Desktop, Cline, etc.)
## Available Resources
- `guides://list` - Lists all available coding guides
- `guides://{guide_name}` - Retrieves the content of a specific guide (e.g., `guides://python.md`)
## Installation
### From Source
```bash
# Clone the repository
git clone https://github.com/delian/codeguide-mcp.git
cd codeguide-mcp
# Install with uv (recommended)
uv sync
# Or with pip
pip install -e .
```
### With Docker
```bash
docker build -t codeguide-mcp .
docker run -i codeguide-mcp
```
### In VS Code
[](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)
Or 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`:
```json
{
"servers": {
"codeguide-mcp": {
"command": "docker",
"args": ["run", "-i", "--rm", "delian/codeguide-mcp"]
}
}
}
```
## Configuration
Configure the server by creating a `config.toml` file or setting environment variables:
### GitHub Configuration (Recommended)
To load guides from a GitHub repository:
```toml
github_repo = "owner/repository" # e.g., "delian/codeguide-mcp"
github_path = "guides" # Path to guides directory in repo
github_branch = "main" # Branch to fetch from
cache_dir = ".guides-cache" # Local cache directory
log_level = "INFO"
```
### Local Directory Configuration
To use local guides only:
```toml
guides_dir = "guides"
log_level = "INFO"
```
### Environment Variables
- `GUIDES_GITHUB_REPO` - GitHub repository (format: `owner/repo`)
- `GUIDES_GITHUB_PATH` - Path to guides directory in repository (default: `guides`)
- `GUIDES_GITHUB_BRANCH` - Branch to fetch from (default: `main`)
- `GUIDES_CACHE_DIR` - Local cache directory (default: `.guides-cache`)
- `GUIDES_DIR` - Local directory containing guide files (default: `guides`)
- `GUIDES_LOG_LEVEL` - Logging level (default: `INFO`)
Transport (see [Remote deployment](#remote-deployment-google-cloud-run)):
- `GUIDES_TRANSPORT` - `stdio`, `streamable-http`, or `auto` (default: `auto` — HTTP when a `PORT` env var is present, stdio otherwise)
- `PORT` - Port to listen on in HTTP mode; takes precedence over `GUIDES_PORT` (Cloud Run injects this)
- `GUIDES_HOST` - Bind address in HTTP mode (default: `0.0.0.0`)
- `GUIDES_HTTP_PATH` - MCP endpoint path (default: `/mcp`)
- `GUIDES_STATELESS_HTTP` - Handle each request independently (default: `true`; required when replicas autoscale)
- `GUIDES_ALLOWED_HOSTS` - Host header allowlist enabling DNS-rebinding protection (default: empty = no Host validation)
### Behavior
1. **Network available + GitHub configured**: Fetches guides from GitHub and caches them locally
2. **Network unavailable**: Uses local cache if available
3. **No cache available**: Falls back to local `guides_dir` if configured
## Remote deployment (Google Cloud Run)
The same image serves both transports: it speaks stdio over a pipe by default,
and switches to Streamable HTTP when a `PORT` env var is present — which Cloud Run
always injects. No separate image or entrypoint is needed.
### 1. Publish the image
```bash
docker build -t delian/codeguide-mcp:0.1.0 -t delian/codeguide-mcp:latest .
docker push delian/codeguide-mcp:0.1.0
docker push delian/codeguide-mcp:latest
```
### 2. Deploy
```bash
gcloud run deploy codeguide-mcp \
--image=docker.io/delian/codeguide-mcp:0.1.0 \
--region=europe-west1 \
--allow-unauthenticated \
--port=8080 \
--set-env-vars=GUIDES_TRANSPORT=streamable-http,GUIDES_GITHUB_REPO= \
--memory=512Mi --cpu=1 \
--min-instances=0 --max-instances=4 --concurrency=40
```
`GUIDES_GITHUB_REPO=` (empty) makes the service serve the guides baked into the
image. Leaving GitHub enabled adds a network round-trip per guide and runs into
the unauthenticated GitHub API limit of 60 requests/hour per egress IP, after
which the server silently falls back to those same baked-in files anyway.
The MCP endpoint is then `https://<service-url>/mcp`:
```bash
gcloud run services describe codeguide-mcp --region=europe-west1 \
--format='value(status.url)'
```
Cloud Run answers on two hostnames for the same service — the
`SERVICE-PROJECTNUMBER.REGION.run.app` form printed by `gcloud run deploy`, and
the older `SERVICE-HASH-REGIONCODE.a.run.app` form that `status.url` reports.
Both are equivalent; either works in a client config.
### 3. Point clients at it
See [Connecting to a remote server](#connecting-to-a-remote-server) below for the
per-client configuration.
### Pulling from Docker Hub
Cloud Run deploys public Docker Hub images directly, but caches them for only an
hour and re-pulls anonymously afterwards, so a scale-up can hit Docker Hub's
anonymous pull limits and fail to start instances. For anything beyond casual
use, mirror through an Artifact Registry remote repository:
```bash
gcloud artifacts repositories create dockerhub \
--repository-format=docker --location=europe-west1 \
--mode=remote-repository --remote-docker-repo=DOCKER-HUB
gcloud run deploy codeguide-mcp \
--image=europe-west1-docker.pkg.dev/PROJECT_ID/dockerhub/delian/codeguide-mcp:0.1.0 \
...
```
### Notes on running it publicly
- `--allow-unauthenticated` makes the endpoint world-callable. The server is
read-only, but the `clear_cache` prompt is reachable by any caller and drops
the in-memory caches, and traffic drives autoscaling cost — keep
`--max-instances` capped. To restrict access, omit the flag and have clients
send an identity token, or front the service with Cloud Armor / API Gateway.
- `GUIDES_STATELESS_HTTP` must stay `true` unless you also enable session
affinity, since Cloud Run may route a session's requests to different instances.
- `GET /` returns 404 by design; only `/mcp` is served. Cloud Run's default
startup probe is a TCP check on `$PORT`, so this is fine — don't configure an
HTTP health check on `/`.
- Set `GUIDES_ALLOWED_HOSTS` to your service hostname to enable Host-header
validation if you expose the service under a custom domain.
## Publishing to the MCP Registry
The MCP servers list in the VS Code Extensions view (type `@mcp` in the search
bar) is fed by the GitHub MCP Registry, which ingests from the official
[MCP Registry](https://registry.modelcontextprotocol.io). Publishing there is
therefore how this server becomes discoverable in VS Code — no VS Code extension
of its own is required.
[`server.json`](server.json) holds the registry metadata: the Docker image for
clients that want to run it locally, and the hosted URL for clients that would
rather not. Ownership of the image is proven by the
`io.modelcontextprotocol.server.name` label in the [Dockerfile](Dockerfile),
whose value **must** equal `.name` in `server.json`.
Authenticate once (an interactive device-code flow), then run the publish script:
```bash
mcp-publisher login github # namespace io.github.<your-username>/*
tools/publish.sh
```
[`tools/publish.sh`](tools/publish.sh) does the whole release: it checks the
required tooling and Docker login, verifies that `server.json` and
`pyproject.toml` agree on the version and that the Dockerfile label matches the
server name, builds and pushes `:VERSION` and `:latest`, validates `server.json`
against the live registry, publishes, then reads the entry back to confirm.
```bash
tools/publish.sh --dry-run # everything except push and publish
tools/publish.sh --version 0.2.0 # bump server.json + pyproject + image tag, then release
tools/publish.sh --skip-build # reuse images already on Docker Hub
```
Install `mcp-publisher` from the
[registry quickstart](https://modelcontextprotocol.io/registry/quickstart) if
you do not have it. After publishing, inclusion in GitHub's curated list may
need a request to `partnerships@github.com`.
## Adding Guides
### Using GitHub (Recommended)
If 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.
### Using Local Directory
Add Markdown files to the `guides/` directory. Each file will be automatically available as a resource.
Example:
```bash
echo "# Python Style Guide\n\nUse PEP 8..." > guides/python.md
```
## Usage with MCP Clients
The server can be consumed two ways:
| Mode | Transport | How the client reaches it |
| --- | --- | --- |
| **Local** | stdio | Client spawns `python main.py` or `docker run -i` and talks over a pipe |
| **Remote** | Streamable HTTP | Client makes HTTPS requests to a hosted `…/mcp` URL |
Local mode needs no network and no hosting; remote mode lets a team share one
deployment and keeps the guides identical for everyone.
### Connecting to a remote server
A deployed instance exposes its MCP endpoint at `/mcp`. The snippets below use the
reference deployment:
```
https://codeguide-mcp-86057491046.europe-west1.run.app/mcp
```
It is public and needs no credentials. Substitute your own URL if you run the
service yourself — see [Remote deployment](#remote-deployment-google-cloud-run).
**VS Code** — `.vscode/mcp.json` for one workspace, or your user `mcp.json` for
every workspace:
```json
{
"servers": {
"codeguide-mcp": {
"type": "http",
"url": "https://codeguide-mcp-86057491046.europe-west1.run.app/mcp"
}
}
}
```
**Claude Code**:
```bash
claude mcp add --transport http codeguide-mcp \
https://codeguide-mcp-86057491046.europe-west1.run.app/mcp
```
**Cursor** — `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (per project):
```json
{
"mcpServers": {
"codeguide-mcp": {
"url": "https://codeguide-mcp-86057491046.europe-west1.run.app/mcp"
}
}
}
```
**Claude Desktop** — add it as a custom connector in Settings, or bridge the
remote endpoint into a stdio client with
[`mcp-remote`](https://www.npmjs.com/package/mcp-remote):
```json
{
"mcpServers": {
"codeguide-mcp": {
"command": "npx",
"args": ["-y", "mcp-remote", "https://codeguide-mcp-86057491046.europe-west1.run.app/mcp"]
}
}
}
```
**Any client** that speaks Streamable HTTP works — point it at the `/mcp` URL.
For servers behind authentication, pass a token with
`--header "Authorization: Bearer $(gcloud auth print-identity-token)"`
(Claude Code) or the client's equivalent `headers` block.
### Verifying a remote endpoint
A single `curl` confirms a deployment is live and public:
```bash
curl -s -X POST https://codeguide-mcp-86057491046.europe-west1.run.app/mcp \
-H 'Content-Type: application/json' \
-H 'Accept: application/json, text/event-stream' \
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{
"protocolVersion":"2025-06-18","capabilities":{},
"clientInfo":{"name":"curl","version":"1"}}}'
```
A healthy server replies with an SSE `event: message` frame containing its
capabilities and instructions. Note that `GET /` returns 404 by design — only
`/mcp` is served.
To exercise every resource, tool, and prompt over HTTP instead:
```bash
uv run python verify_server.py --http https://codeguide-mcp-86057491046.europe-west1.run.app/mcp
```
### Local usage
#### Claude Desktop
Add to your `mcp.json`:
```json
{
"mcpServers": {
"coding-guides": {
"command": "python",
"args": ["-m", "main"]
}
}
}
```
or
```json
{
"mcpServers": {
"coding-guides": {
"command": "docker",
"args": ["run", "--rm", "-i", "docker.io/delian/codeguide-mcp"]
}
}
}
```
### Other MCP Clients
Run the server and connect via stdio:
```bash
python main.py
```
## Development
```bash
# Install development dependencies
uv pip install -e ".[dev]"
# Run pre-commit hooks
pre-commit install
pre-commit run --all-files
# Run the server
python main.py
```
## License
MIT
## Contributing
Contributions welcome! Please open an issue or pull request.