cubrid-mcp-server AGENTS.md

AGENTS.md

Guidance for AI agents and contributors working in this repository.

Project Overview

cubrid-mcp-server is a Model Context Protocol server for the CUBRID database. It lets LLM clients safely inspect schemas and run read-only queries via the pure-Python pycubrid driver.

• Package: cubrid_mcp_server/
• Entry point: python -m cubrid_mcp_server
• Tool surface (see README.md): schema inspection, index/serial/class-hierarchy listing, explain_query, execute_query (read-only), health_check.

Architecture

cubrid_mcp_server/
├── server.py     # MCP server + tool definitions
├── database.py   # pycubrid connection + query execution
├── safety.py     # read-only SQL enforcement / whitelist
├── config.py     # environment-variable configuration
├── context.py    # request/connection context
└── __main__.py   # module entry point

Code Conventions

• Python 3.10+, fully typed (py.typed); keep mypy and ruff clean.
• All logging MUST be routed to stderr. stdout is reserved for the MCP protocol stream — never print to stdout.
• Read-only safety is a core invariant: any change touching safety.py / query execution must preserve read-only enforcement and ship tests.

Development

• make install — install in development mode
• make check — ruff lint + mypy typecheck
• make test — unit tests (excludes integration)
• make integration — integration tests (requires a live CUBRID)
• make release VERSION=x.y.z — release commit + tag

Release Process

Version is single-sourced from cubrid_mcp_server/__init__.py → __version__ = "x.y.z".

Steps:

1. Bump the version and add a dated changelog entry in CHANGELOG.md (## [x.y.z] - YYYY-MM-DD).
2. Open a PR and merge to main.
3. Push the tag on the merged commit: git tag vx.y.z <merged-sha> && git push origin vx.y.z.
4. The tag push triggers .github/workflows/create-release.yml, which extracts the ## [x.y.z] - YYYY-MM-DD section from CHANGELOG.md (fail-closed — no fallback) and creates the GitHub Release titled vx.y.z with that body, after verifying the tag is an ancestor of origin/main.
5. Publishing the GitHub Release triggers .github/workflows/publish-pypi.yml, which rebuilds, verifies, and publishes to PyPI via Trusted Publisher (OIDC).