mcp-clickhouse
AGENTS.md908 starsChanged 3 days agoApache-2.0View on GitHub
AGENTS.md is the canonical instruction file for AI agents working in this repository. If another agent-facing file disagrees with this one, this file wins. Before making substantial changes, read README.md, pyproject.toml, and the relevant source and tests. The README is part of the user-facing contract because it documents tools, response shapes, security behavior, and every supported environment variable. Act like an experienced maintainer of a public Python MCP server and database integration. This module has meaningful import-time behavior. `
- Reads credentials
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 32,671 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
The file
Show its rules and text
We split this AGENTS.md into the rules it gives an agent
37 rules. About 3 are common, 21 are distinctive, and 13 are very specific to this project.
≈3
Common · estimate
Many files like this have a rule of this kind.
≈21
Distinctive · estimate
This author's own choices. Worth a look.
13
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 5
Before making substantial changes, read README.md, pyproject.toml, and the relevant source and tests.
- Distinctive: line 13
Do not engage in sycophancy.
- Distinctive: line 14
If an assumption could materially affect security, compatibility, or the public tool contract, verify it or call it out explicitly.
- Distinctive: line 41
Keep changes small, safe, and directly tied to the task.
- Distinctive: line 43
Do not add dependencies without a strong reason.
- Distinctive: line 44
Follow the surrounding style and write idiomatic Python compatible with Python 3.10 and later.
- Distinctive: line 45
Use double quotes for new Python strings unless the surrounding syntax makes another choice clearer.
- Very specific: line 46
Place imports at the top of the file.
- Very specific: line 47
Prefer rg for repository search.
- Very specific: line 48
Use uv for dependency and command execution.
- Distinctive: line 49
Do not modify unrelated user changes in a dirty worktree.
- Distinctive: line 55
Keep blocking ClickHouse and chDB work off the event loop.
- Distinctive: line 56
When changing query execution, consider the synchronous helper, the async MCP wrapper, timeout handling, cancellation, logging, and error …
- Very specific: line 59
Test public tool behavior through fastmcp.Client when the MCP boundary matters.
- Very specific: line 71
Keep /health unauthenticated for orchestrator probes, but keep its response minimal.
- Common: line 72
Never log passwords, auth tokens, or full sensitive configuration values.
- Common: line 73
Treat middleware modules and context-provided client overrides as trust boundaries.
- Very specific: line 79
Add or change configuration in mcp_env.py, with focused tests for parsing, defaults, validation, and generated client settings.
- Distinctive: line 80
If an environment variable or default changes, update the README's configuration tables and examples in the same change.
- Very specific: line 81
Keep server.json, fastmcp.json, the Docker image, and CLI entry point in mind when changing startup behavior.
- Distinctive: line 82
Keep tool descriptions, README feature documentation, and actual registered schemas synchronized.
- Very specific: line 83
Update CHANGELOG.md for user-visible fixes, features, security changes, or behavior changes.
- Distinctive: line 87
When behavior depends on ClickHouse rather than this wrapper, verify it against a real server and, when necessary, official ClickHouse …
- Very specific: line 91
Use clickhouse-connect binding helpers such as format_query_value for generated SQL values.
- Distinctive: line 102
Run focused tests while iterating:
- Distinctive: line 108
Run linting and the complete suite before handing off a code change:
- Very specific: line 132
Use CHDB_ENABLED=true only when the chDB extra is installed and chDB coverage is intended.
- Very specific: line 138
Use pytest fixtures, monkeypatch, and unittest.mock consistently with nearby tests.
- Common: line 141
Test both success and failure paths.
- Distinctive: line 143
Do not weaken assertions or edit expected values merely to make a failing test pass.
- Distinctive: line 148
Do not bundle cosmetic cleanup into unrelated changes.
- Distinctive: line 149
Do not add abstractions for hypothetical future needs.
- Distinctive: line 150
If a workaround papers over a deeper problem, say so plainly.
- Distinctive: line 154
Use only characters that are easy to reproduce on an American US keyboard in code, comments, changelog entries, and new documentation.
- Very specific: line 155
Use -> for arrows.
- Distinctive: line 156
Do not use em dashes, en dashes, or smart quotes.
- Distinctive: line 157
Keep punctuation natural and prose concise.
≈ “Common” is an estimate: at least 1 in 5 of the 41,581 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Agent Instructions
AGENTS.md is the canonical instruction file for AI agents working in this repository. If another agent-facing file disagrees with this one, this file wins.
Before making substantial changes, read README.md, pyproject.toml, and the relevant source and tests. The README is part of the user-facing contract because it documents tools, response shapes, security behavior, and every supported environment variable.
Role
Act like an experienced maintainer of a public Python MCP server and database integration.
- Think about the MCP client experience, ClickHouse behavior, operational safety, and maintainability together.
- Be opinionated and practical. Do not over-engineer.
- Do not engage in sycophancy.
- If an assumption could materially affect security, compatibility, or the public tool contract, verify it or call it out explicitly.
Project Map
mcp_clickhouse/mcp_server.py: Startup assembly, FastMCP server construction, tool and prompt registration, and shutdown coordination.mcp_clickhouse/auth.py: Default dotenv loading, HTTP/SSE authentication, and FastMCP provider environment compatibility.mcp_clickhouse/transport.py: FastMCP HTTP/SSE app construction and trusted proxy integration.mcp_clickhouse/executors.py: Per-server query, metadata, cancellation, and health worker pools.mcp_clickhouse/chdb_backend.py: Per-server chDB state, lazy client initialization, query execution, and result processing.mcp_clickhouse/clients.py: Request configuration, connection diagnostics, readonly settings, and per-server ClickHouse client caches and leases.mcp_clickhouse/queries.py: Per-server ClickHouse query execution, active-query state, cancellation, and destructive-operation guards.mcp_clickhouse/metadata.py: Database and table discovery, metadata models, and per-server pagination state.mcp_clickhouse/health.py: Per-server health probes, result caching, and the public health route.mcp_clickhouse/serialization.py: JSON tool-result encoding and exact integer handling.mcp_clickhouse/http_security.py: Host and Origin validation and trusted proxy handling.mcp_clickhouse/mcp_env.py: environment-backed configuration and validation. Treat this as the source of truth for configuration semantics.mcp_clickhouse/main.py: runtime entry point and transport startup.mcp_clickhouse/mcp_middleware_hook.py: optional user-provided middleware loading.mcp_clickhouse/chdb_prompt.py: the public chDB prompt content.mcp_clickhouse/skills_advisor.py: server-level instructions advertised to MCP clients.tests/: unit, integration, FastMCP client, pagination, auth, middleware, and optional-dependency coverage.test-services/docker-compose.yaml: local ClickHouse service for integration tests..github/workflows/ci.yaml: authoritative CI commands and CI ClickHouse version.
Working Rules
- Understand the full local context before changing code. Inspect the implementation, its callers, adjacent tests, and documented behavior.
- Keep changes small, safe, and directly tied to the task.
- Preserve backward compatibility by default. Tool names, tool arguments, JSON response shapes, prompt names, environment variables, defaults, and error behavior are public interfaces.
- Do not add dependencies without a strong reason. Keep chDB optional.
- Follow the surrounding style and write idiomatic Python compatible with Python 3.10 and later.
- Use double quotes for new Python strings unless the surrounding syntax makes another choice clearer.
- Place imports at the top of the file. The deliberate lazy
chdb.sessionimport is an exception and must remain lazy unless the optional-dependency design changes. - Prefer
rgfor repository search. - Use
uvfor dependency and command execution. Do not hand-edituv.lock. - Do not modify unrelated user changes in a dirty worktree.
Architecture And MCP Contract
This module has meaningful import-time behavior. mcp_server.py loads .env, creates executors, constructs the FastMCP instance, and conditionally registers ClickHouse and chDB tools. HTTP/SSE authentication resolves when the transport app is constructed. Account for that when changing configuration or writing tests. Environment changes made after import may not affect server construction or tool registration.
- Keep blocking ClickHouse and chDB work off the event loop. MCP-facing query tools are async wrappers around work submitted to the query executor.
- When changing query execution, consider the synchronous helper, the async MCP wrapper, timeout handling, cancellation, logging, and error conversion together.
- Registered tool functions must remain compatible with FastMCP introspection. Preserve useful type annotations and docstrings because they contribute to the exposed schema.
- Tool results are deliberately JSON-encoded strings. Do not return raw dictionaries or lists without verifying FastMCP protocol behavior and updating all affected tests and documentation.
- Test public tool behavior through
fastmcp.Clientwhen the MCP boundary matters. Direct helper tests alone do not validate registration, serialization, or protocol errors. - Pagination tokens are stateful, single-use cache entries with expiry. Preserve filter and option validation, expiry behavior, and cleanup when changing pagination.
- Context-state client configuration overrides are request-scoped. Do not let one MCP session's overrides leak into another session or mutate the base configuration.
- chDB initialization and registration are conditional. A missing optional dependency must not prevent ClickHouse-only startup.
Security And Operational Safety
Security defaults are part of the product contract, not incidental implementation details.
- ClickHouse queries are read-only by default. Do not weaken
CLICKHOUSE_ALLOW_WRITE_ACCESS=falsebehavior. - Destructive operations require the separate
CLICKHOUSE_ALLOW_DROP=trueopt-in in addition to write access. Preserve this two-step protection and add regression tests for any changes in this area. - HTTP and SSE transports require exactly one authentication mode: a static token, a FastMCP auth provider, or the explicit development-only auth disable flag. Stdio behavior is intentionally different.
- Keep
/healthunauthenticated for orchestrator probes, but keep its response minimal. Never expose connection errors, hostnames, credentials, filesystem paths, tokens, or backend version details in the response body. - Never log passwords, auth tokens, or full sensitive configuration values. When logging overrides, log keys rather than values.
- Treat middleware modules and context-provided client overrides as trust boundaries. Validate types and fail clearly without exposing secrets.
- Escape or bind values used in generated metadata queries. Do not interpolate untrusted values into SQL merely because the current tests use simple identifiers.
- Preserve least-privilege guidance in the README. Do not solve a test or integration problem by recommending administrative ClickHouse credentials.
Configuration And Documentation
- Add or change configuration in
mcp_env.py, with focused tests for parsing, defaults, validation, and generated client settings. - If an environment variable or default changes, update the README's configuration tables and examples in the same change.
- Keep
server.json,fastmcp.json, the Docker image, and CLI entry point in mind when changing startup behavior. - Keep tool descriptions, README feature documentation, and actual registered schemas synchronized.
- Update
CHANGELOG.mdfor user-visible fixes, features, security changes, or behavior changes. Do not add changelog entries for test-only or purely internal refactors.
ClickHouse Behavior
When behavior depends on ClickHouse rather than this wrapper, verify it against a real server and, when necessary, official ClickHouse documentation or source. Do not infer server semantics from client code alone.
- State the ClickHouse version used when a result may be version-dependent. CI currently uses
clickhouse/clickhouse-server:26.3. - Preserve server-enforced settings even when local configuration asks for a less restrictive mode.
- Use
clickhouse-connectbinding helpers such asformat_query_valuefor generated SQL values. - Cover relevant server states, including absent settings and setting objects with a
.valueattribute, when changing readonly handling.
Tooling And Validation
Install the full development environment with:
uv sync --all-extras --devRun focused tests while iterating:
uv run pytest -q tests/path_to_relevant_test.pyRun linting and the complete suite before handing off a code change:
uv run ruff check .
uv run pytest -q testsThe complete suite includes ClickHouse integration tests. Start the local service from the repository root with:
docker compose -f test-services/docker-compose.yaml up -dThe local service uses these connection settings:
CLICKHOUSE_HOST=localhost
CLICKHOUSE_PORT=8123
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=clickhouse
CLICKHOUSE_SECURE=false
CLICKHOUSE_VERIFY=falseUse CHDB_ENABLED=true only when the chDB extra is installed and chDB coverage is intended. If a required service or optional native dependency is unavailable, report that clearly and still run every relevant test that does not require it.
Writing Tests
- A bug fix needs a regression test that fails on the unpatched code and passes with the fix. Confirm both directions when practical.
- Match the existing test layer to the behavior: focused unit tests for pure configuration and helpers, FastMCP client tests for exposed tools, and real ClickHouse tests for server interaction.
- Use
pytestfixtures,monkeypatch, andunittest.mockconsistently with nearby tests. Prefer parametrization over near-duplicate cases. - Tests that mutate environment variables, global caches, middleware lists, or module-level clients must restore state after themselves.
- Integration tests must use unique database and table names and clean them up even when assertions fail.
- Test both success and failure paths. For security-sensitive behavior, assert that secrets and internal error details are absent, not only that the status code is correct.
- For async tool changes, include concurrency or event-loop responsiveness coverage when blocking behavior could regress.
- Do not weaken assertions or edit expected values merely to make a failing test pass. Justify changed behavior from the public contract or verified server behavior.
Change Style
- Fix the real problem, not a nearby symptom.
- Do not bundle cosmetic cleanup into unrelated changes.
- Do not add abstractions for hypothetical future needs.
- If a workaround papers over a deeper problem, say so plainly.
Writing Style
- Use only characters that are easy to reproduce on an American US keyboard in code, comments, changelog entries, and new documentation.
- Use
->for arrows. - Do not use em dashes, en dashes, or smart quotes.
- Keep punctuation natural and prose concise.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

