agentleFS
ClickHouseClickHouse/mcp-clickhouse/AGENTS.md

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.

  • In this repository2 other files it gives its agents.

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
  1. Very specific:

    Before making substantial changes, read README.md, pyproject.toml, and the relevant source and tests.

    line 5
  2. Distinctive:

    Do not engage in sycophancy.

    line 13
  3. Distinctive:

    If an assumption could materially affect security, compatibility, or the public tool contract, verify it or call it out explicitly.

    line 14
  4. Distinctive:

    Keep changes small, safe, and directly tied to the task.

    line 41
  5. Distinctive:

    Do not add dependencies without a strong reason.

    line 43
  6. Distinctive:

    Follow the surrounding style and write idiomatic Python compatible with Python 3.10 and later.

    line 44
  7. Distinctive:

    Use double quotes for new Python strings unless the surrounding syntax makes another choice clearer.

    line 45
  8. Very specific:

    Place imports at the top of the file.

    line 46
  9. Very specific:

    Prefer rg for repository search.

    line 47
  10. Very specific:

    Use uv for dependency and command execution.

    line 48
  11. Distinctive:

    Do not modify unrelated user changes in a dirty worktree.

    line 49
  12. Distinctive:

    Keep blocking ClickHouse and chDB work off the event loop.

    line 55
  13. Distinctive:

    When changing query execution, consider the synchronous helper, the async MCP wrapper, timeout handling, cancellation, logging, and error …

    line 56
  14. Very specific:

    Test public tool behavior through fastmcp.Client when the MCP boundary matters.

    line 59
  15. Very specific:

    Keep /health unauthenticated for orchestrator probes, but keep its response minimal.

    line 71
  16. Common:

    Never log passwords, auth tokens, or full sensitive configuration values.

    line 72
  17. Common:

    Treat middleware modules and context-provided client overrides as trust boundaries.

    line 73
  18. Very specific:

    Add or change configuration in mcp_env.py, with focused tests for parsing, defaults, validation, and generated client settings.

    line 79
  19. Distinctive:

    If an environment variable or default changes, update the README's configuration tables and examples in the same change.

    line 80
  20. Very specific:

    Keep server.json, fastmcp.json, the Docker image, and CLI entry point in mind when changing startup behavior.

    line 81
  21. Distinctive:

    Keep tool descriptions, README feature documentation, and actual registered schemas synchronized.

    line 82
  22. Very specific:

    Update CHANGELOG.md for user-visible fixes, features, security changes, or behavior changes.

    line 83
  23. Distinctive:

    When behavior depends on ClickHouse rather than this wrapper, verify it against a real server and, when necessary, official ClickHouse …

    line 87
  24. Very specific:

    Use clickhouse-connect binding helpers such as format_query_value for generated SQL values.

    line 91
  25. Distinctive:

    Run focused tests while iterating:

    line 102
  26. Distinctive:

    Run linting and the complete suite before handing off a code change:

    line 108
  27. Very specific:

    Use CHDB_ENABLED=true only when the chDB extra is installed and chDB coverage is intended.

    line 132
  28. Very specific:

    Use pytest fixtures, monkeypatch, and unittest.mock consistently with nearby tests.

    line 138
  29. Common:

    Test both success and failure paths.

    line 141
  30. Distinctive:

    Do not weaken assertions or edit expected values merely to make a failing test pass.

    line 143
  31. Distinctive:

    Do not bundle cosmetic cleanup into unrelated changes.

    line 148
  32. Distinctive:

    Do not add abstractions for hypothetical future needs.

    line 149
  33. Distinctive:

    If a workaround papers over a deeper problem, say so plainly.

    line 150
  34. Distinctive:

    Use only characters that are easy to reproduce on an American US keyboard in code, comments, changelog entries, and new documentation.

    line 154
  35. Very specific:

    Use -> for arrows.

    line 155
  36. Distinctive:

    Do not use em dashes, en dashes, or smart quotes.

    line 156
  37. Distinctive:

    Keep punctuation natural and prose concise.

    line 157

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
AGENTS.md

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.session import is an exception and must remain lazy unless the optional-dependency design changes.
  • Prefer rg for repository search.
  • Use uv for dependency and command execution. Do not hand-edit uv.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.Client when 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=false behavior.
  • Destructive operations require the separate CLICKHOUSE_ALLOW_DROP=true opt-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 /health unauthenticated 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.md for 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-connect binding helpers such as format_query_value for generated SQL values.
  • Cover relevant server states, including absent settings and setting objects with a .value attribute, when changing readonly handling.

Tooling And Validation

Install the full development environment with:

uv sync --all-extras --dev

Run focused tests while iterating:

uv run pytest -q tests/path_to_relevant_test.py

Run linting and the complete suite before handing off a code change:

uv run ruff check .
uv run pytest -q tests

The complete suite includes ClickHouse integration tests. Start the local service from the repository root with:

docker compose -f test-services/docker-compose.yaml up -d

The local service uses these connection settings:

CLICKHOUSE_HOST=localhost
CLICKHOUSE_PORT=8123
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=clickhouse
CLICKHOUSE_SECURE=false
CLICKHOUSE_VERIFY=false

Use 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 pytest fixtures, monkeypatch, and unittest.mock consistently 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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.