Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 25 additions & 0 deletions .github/workflows/mcp-tests.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
name: MCP integration tests

on:
pull_request:
branches: [master]
paths:
- 'src/**'
- 'tests/**'
- 'pyproject.toml'
- 'uv.lock'
- '.github/workflows/mcp-tests.yml'

jobs:
test:
runs-on: ubuntu-latest
strategy:
matrix:
python: ['3.10', '3.13']
steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v4
with:
python-version: ${{ matrix.python }}
- run: python -m pip install -e '.[mcp,tools]' pytest pytest-asyncio
- run: python -m pytest -q
9 changes: 9 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -206,3 +206,12 @@ the [MIT License](https://opensource.org/licenses/MIT). 커뮤니티: [Discord](
<a href="https://github.com/CausalInferenceLab/lang2sql/graphs/contributors">
<img src="https://contrib.rocks/image?repo=CausalInferenceLab/lang2sql" />
</a>

## Coding-agent MCP connection

Codex/Claude Code can use the existing DB and business-definition tools through
an optional stdio adapter, without the internal agent loop or an LLM API key.
See [MCP setup and limitations](docs/mcp.md).

For direct shell tool calls without MCP or an internal LLM, see the
[`lang2sql-tools` CLI](docs/tool_cli.md).
113 changes: 113 additions & 0 deletions docs/mcp.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,113 @@
# Lang2SQL MCP for coding agents

Codex or Claude Code owns the conversation and tool-calling loop. This optional
stdio server forwards calls to Lang2SQL's existing tool registry; it does not run
`agent_loop`, instantiate an LLM provider, or require an OpenAI API key.
The CLI/Discord harness, core ports, SQL safety pipeline and existing tools are
unchanged. `HarnessContext` is reused with an inert session and an LLM that raises
if called. Concrete dependencies are assembled separately under `tenancy/tool_runtime.py`.

## Install and connect

From the checkout:

```sh
uv sync --extra mcp
# Add the matching existing DB extra for other databases, e.g.:
# uv sync --extra mcp --extra postgres
```

One server process uses one DB connection and one fixed identity. Set the existing
`LANG2SQL_DB_URL` (and optionally `LANG2SQL_DB_SCHEMA`) or the existing D1 variables.
The server fails at startup if no connection is configured; it does not use the
CLI's stub DB. Configure a read-only source DB account. Metadata changes still
write to Lang2SQL's separate SQLite store.

Replace the paths below with absolute paths. The SQLite source database must
already exist. These commands register a server in the client; installation of
Lang2SQL itself does not change client configuration.

Codex CLI:

```sh
codex mcp add lang2sql --env LANG2SQL_DB_URL=sqlite:////absolute/path/analytics.db -- \
/absolute/path/Lang2SQL/.venv/bin/lang2sql-mcp \
--user-id analyst --org-id demo --team-id finance \
--store /absolute/path/lang2sql-metadata.db
```

Claude Code:

```sh
claude mcp add --transport stdio lang2sql \
--env LANG2SQL_DB_URL=sqlite:////absolute/path/analytics.db -- \
/absolute/path/Lang2SQL/.venv/bin/lang2sql-mcp \
--user-id analyst --org-id demo --team-id finance \
--store /absolute/path/lang2sql-metadata.db
```

CLI argument forms were checked against the locally installed clients' `mcp add
--help`. Protocol integration is tested using the official Python MCP client;
interactive Codex/Claude conversations are not an automated test requirement.

The parent directory for `--store` must exist. Without `--store`, metadata and audit
are in-memory. Pass `--admin` only when the local operator should be able to write
org-level definitions. User/org/team/admin values come from startup arguments,
not model-supplied tool arguments. This is a local, single-identity adapter, not
remote authentication or a multi-tenant HTTP server. Use a distinct metadata store
per DB to avoid mixing definitions between databases. Shared user-level definitions
retain the existing federation semantics across teams within an organization.

## Tools

| Name | Behavior |
|---|---|
| `explore_schema` | List tables or describe a table, including cached descriptions. |
| `run_sql` | Existing SQL validation, execution, audit and text result formatting. |
| `term_custom` | Existing org/team/user definitions; `list=true` reads effective definitions; registration/removal retains existing permissions. |
| `remember` | Save a note in this server process for the configured user. |
| `recall_memory` | Call the existing memory service. The default inject-all retriever returns all notes, not semantic search. |

Example client request: “Use Lang2SQL to inspect the schema and business
definitions, then calculate total revenue.” The agent should call
`term_custom({"list": true})` explicitly: the old harness's automatic system-prompt
injection does not run here. Notes are observations, not approved instructions.

`remember` notes are process-local and disappear on restart even when `--store` is
set. Business definitions and audits persist with `--store`. No new memory
algorithm, alias gate, graph experiment or extraction model is included.

`ask_user`, `enrich_schema`, `org_setup`, `ingest_doc` and `confirm_ingest` are not
advertised. The external agent asks the user directly. LLM-driven enrichment and
document ingestion remain available in existing frontends.

## Protocol and limitations

- Tool schemas come from existing `ToolSpec`; the MCP boundary rejects extra
arguments and the SDK validates declared types before dispatch.
- Existing `ToolResult.content` becomes MCP text content; `is_error` becomes
`isError`. SQL output remains the existing text table (first 50 rows shown),
not a new structured result or export API.
- SQL `NEEDS CONFIRMATION` is forwarded as existing text without executing the
query. This adapter adds no approval bypass or automatic resume mechanism.
- Calls share one registry/store and are serialized in a worker thread. Existing
synchronous SQLite KV operations do not block the transport event loop.
Cancellation of a request does not guarantee cancellation of an executing DB
query; the worker retains the store lock until completion.
- Logs use stderr; stdout carries only MCP messages. No HTTP server or listener
is started. Environment credentials are not advertised as tool parameters.
- Existing DB adapter and SQL safety limitations remain; this PR does not add
database-side timeout guarantees or a new SQL parser.

## Verification

```sh
uv run --extra mcp pytest -q
uv run --extra mcp python bench/ecommerce_demo.py
```

The stdio tests launch the actual server process and check handshake, tool listing,
schema discovery, SQL execution, blocked DDL, input errors, unavailable tools,
metadata permission checks, team scoping, persistence and process-local notes.

For direct command-line calls using the same runtime, see [tool CLI](tool_cli.md).
54 changes: 54 additions & 0 deletions docs/tool_cli.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,54 @@
# Direct tool CLI for coding agents

`lang2sql-tools` exposes the same five tools as the MCP adapter without MCP,
an internal LLM, or an API key. The original `lang2sql "question"` command is
unchanged. Both adapters share `tenancy/tool_runtime.py` and the existing tools.

```sh
uv sync --extra tools
export LANG2SQL_DB_URL=sqlite:////absolute/path/analytics.db

lang2sql-tools --user-id analyst --org-id demo list
lang2sql-tools --user-id analyst --org-id demo call explore_schema
lang2sql-tools --user-id analyst --org-id demo call run_sql \
--args '{"sql":"SELECT COUNT(*) AS n FROM orders"}'
```

Use `.venv/bin/lang2sql-tools` or `uv run --extra tools lang2sql-tools` when the
virtualenv is not activated. Install the matching DB extra for other databases.
A configured DB is required even for `list`. No DB or LLM stub is used.

`list` returns names, descriptions and argument schemas as JSON. `call` returns
`call_id`, `content`, and `is_error`; SQL content remains the existing text table.
Tool errors exit 1. JSON/schema/config input errors exit 2. Success exits 0.
Argument-parser usage errors go to stderr. Normal results go to stdout as one JSON
value; logs go to stderr. Extra tool arguments (including identity overrides) are
rejected. Operator identity is configured before the subcommand with `--user-id`,
`--org-id`, optional `--team-id` and `--admin`, just as for the MCP server.

For arguments containing quotes or large text, `--args-file /path/to/input.json`
reads a UTF-8 JSON file; `--args-file -` reads stdin. It is exclusive with `--args`.

## Memory and batches

`--store /absolute/path/metadata.db` persists definitions/audits, not memory notes.
Each CLI invocation starts a new memory store. To remember and recall within the
same invocation, pass an array of calls to `batch`:

```sh
lang2sql-tools --user-id analyst --org-id demo batch --args '[
{"name":"remember","arguments":{"text":"Exclude refunds"}},
{"name":"recall_memory","arguments":{"query":"refunds"}}
]'
```

All schemas are validated before the first call. Calls then run sequentially and
stop at the first tool error. The JSON result includes `results`, `completed`, and
`requested`. Successful earlier writes are not rolled back. This is not a database
transaction or a persistent agent session. Notes disappear after the batch exits.
For lasting definitions, use `term_custom` and the same `--store` in later calls.

DB permissions, federation scope, and SQL safety use the same code as the MCP
adapter. See [MCP limitations](mcp.md). Oracle-specific support is in PR #257 and
must be merged before this branch can claim end-to-end Oracle compatibility;
this CLI does not add or duplicate dialect handling.
4 changes: 4 additions & 0 deletions pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,8 @@ dependencies = [
]

[project.optional-dependencies]
tools = ["jsonschema>=4.20,<5"]
mcp = ["mcp>=1.26,<2"]
# DB driver extras. The SQLAlchemyExplorer is dialect-agnostic; install only the
# drivers you connect to. Cloudflare D1 needs no driver (HTTP API via stdlib).
postgres = ["psycopg[binary]>=3.2,<4.0"]
Expand All @@ -36,6 +38,8 @@ all-db = [

[project.scripts]
lang2sql = "lang2sql.frontends.cli.app:main"
lang2sql-tools = "lang2sql.frontends.cli.tools:main"
lang2sql-mcp = "lang2sql.frontends.mcp.server:main"
lang2sql-bot = "lang2sql.frontends.discord.bot:run"

[project.urls]
Expand Down
155 changes: 155 additions & 0 deletions src/lang2sql/frontends/cli/tools.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,155 @@
"""Invoke existing tools directly, without an LLM or MCP transport."""

from __future__ import annotations

import argparse
import asyncio
import json
import logging
import sys
import uuid
from dataclasses import asdict
from pathlib import Path
from typing import Any

from jsonschema import ValidationError, validate

from ...core.identity import Identity
from ...tenancy.tool_runtime import build_tool_context

logger = logging.getLogger(__name__)


async def execute(ctx, calls):
results = []
for call in calls:
call_id = uuid.uuid4().hex
logger.info("cli_tool_start tool=%s call_id=%s", call["name"], call_id)
result = await ctx.tools.dispatch(call["name"], call["arguments"], ctx, call_id)
results.append(asdict(result))
if result.is_error:
logger.warning("cli_tool_failed tool=%s call_id=%s", call["name"], call_id)
break
logger.info("cli_tool_done tool=%s call_id=%s", call["name"], call_id)
return results


def main(argv=None) -> int:
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("--user-id", required=True)
parser.add_argument("--org-id", required=True)
parser.add_argument("--team-id")
parser.add_argument("--admin", action="store_true")
parser.add_argument("--store", default=":memory:")
commands = parser.add_subparsers(dest="command", required=True)
commands.add_parser("list", help="Print tool names and JSON argument schemas")
call_parser = commands.add_parser("call", help="Invoke one tool")
call_parser.add_argument("name")
batch = commands.add_parser(
"batch", help="Run a JSON array of calls in one process"
)
for command in (call_parser, batch):
source = command.add_mutually_exclusive_group()
source.add_argument(
"--args", default=None, help="JSON object, or array for batch"
)
source.add_argument(
"--args-file", help="Read JSON from a file; '-' reads stdin"
)
args = parser.parse_args(argv)
logging.basicConfig(level=logging.INFO)
ctx = None
output: dict[str, Any]
try:
if not args.user_id.strip() or not args.org_id.strip():
raise ValueError("user and org IDs must not be blank")
ctx = build_tool_context(
Identity(
user_id=args.user_id,
guild_id=args.org_id,
channel_id=args.team_id,
is_admin=args.admin,
),
store_path=args.store,
)
specs = {spec.name: spec for spec in ctx.tools.specs()}
if args.command == "list":
output = {
"tools": [
{
**asdict(spec),
"parameters": {
**spec.parameters,
"additionalProperties": False,
},
}
for spec in specs.values()
]
}
status = 0
else:
raw = (
args.args
if args.args is not None
else ("[]" if args.command == "batch" else "{}")
)
if args.args_file:
raw = (
sys.stdin.read()
if args.args_file == "-"
else Path(args.args_file).read_text()
)
value = json.loads(raw)
calls = (
value
if args.command == "batch"
else [{"name": args.name, "arguments": value}]
)
validate(
calls,
{
"type": "array",
"minItems": 1,
"items": {
"type": "object",
"required": ["name", "arguments"],
"properties": {
"name": {"type": "string"},
"arguments": {"type": "object"},
},
"additionalProperties": False,
},
},
)
# Validate the whole batch before any tool performs a metadata write.
for call in calls:
if call["name"] not in specs:
raise ValueError(f"unknown tool: {call['name']}")
validate(
call["arguments"],
{**specs[call["name"]].parameters, "additionalProperties": False},
)
results = asyncio.run(execute(ctx, calls))
output = (
results[0]
if args.command == "call"
else {
"results": results,
"completed": len(results),
"requested": len(calls),
}
)
status = 1 if any(result["is_error"] for result in results) else 0
except (ValueError, OSError, ValidationError) as exc:
logger.warning("cli_input_failed error_type=%s", type(exc).__name__)
output = {"is_error": True, "content": str(exc)}
status = 2
finally:
if ctx is not None and ctx.store is not None:
ctx.store.close()
print(json.dumps(output, ensure_ascii=False))
return status


if __name__ == "__main__":
raise SystemExit(main())
1 change: 1 addition & 0 deletions src/lang2sql/frontends/mcp/__init__.py
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
"""Optional stdio MCP transport for external coding-agent harnesses."""
Loading
Loading