feat: resolve MCP pipeline source from project config - #80
Open
mingjerli wants to merge 1 commit into
Open
Conversation
Plugin hosts spawn the MCP server with no arguments, but --pipeline was required and a missing value killed the process during the MCP handshake — which surfaces in clients as a dead server with no explanation. Add clgraph.mcp.config, which answers "what has this project been configured to index?" in order: --pipeline argument, $CLGRAPH_PIPELINE, clgraph.toml, [tool.clgraph] in pyproject.toml, then a cached .clgraph/pipeline.json. An unconfigured project resolves to None and the server starts anyway: all 14 tools register with their real schemas and return a message naming the fix, so an agent can recover on its own. Deliberately absent: silent directory sniffing. Guessing a SQL directory is only safe when the dialect is also known, and the dialect is now never defaulted. sqlglot parses most of a corpus under the wrong grammar without erroring, so the old bigquery fallback produced lineage graphs that looked right and were not. Pointing at SQL files without a dialect is now an error naming the fix. JSON pipelines are unaffected — they carry their own. Also adds the clgraph-mcp console script so client configs can invoke the server directly rather than through python -m. Breaking: `--pipeline <dir>` without `--dialect` no longer parses as BigQuery. Two CLI tests encoded that default and were updated.
6 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Step 1 of packaging clgraph as a coding-agent plugin: A1 (config resolution + soft-fail startup) and A5 (
clgraph-mcpconsole script).Why
Plugin hosts spawn the MCP server with no arguments, but
--pipelinewasrequired=Truein bothserver.py:303andcli.py:258. A missing value killed the process during the MCP handshake, which surfaces in clients as a dead server with no explanation — invisible to the agent, unactionable for the user.What changed
New
clgraph.mcp.configanswers one question: what has this project been configured to index? First hit wins:--pipeline/--dialectarguments$CLGRAPH_PIPELINE/$CLGRAPH_DIALECTclgraph.toml(top-levelsql_dir,dialect)[tool.clgraph]inpyproject.toml.clgraph/pipeline.jsonNonePaths resolve against the config file's own directory, not the cwd — the server may be spawned from anywhere in the tree.
Soft-fail startup.
create_mcp_server()andrun_mcp_server()acceptpipeline=None. An unconfigured server still registers all 14 tools with their real schemas; each returns a message naming the fix. An agent that can read the error recovers on its own.No silent discovery. Directory sniffing (
models/,sql/,queries/) is deliberately absent. Guessing a source is only safe when the dialect is also known, and discovery now belongs in setup, where it proposes to a human.clgraph-mcpconsole script, so client configs invoke the server directly instead of throughpython -m.Breaking change
The dialect is no longer defaulted to
bigquerywhen indexing SQL files.clgraph-mcp --pipeline ./queries/without--dialectnow exits with guidance.sqlglot parses most of a corpus under the wrong grammar without erroring, so the old fallback produced lineage graphs that looked right and were not — the worst failure mode for a tool an agent will trust. JSON pipelines are unaffected; they carry their own dialect.
Two CLI tests encoded the old default and were updated, with comments explaining why.
Test plan
tests/test_mcp_config.py— 22 new tests: full resolution matrix, precedence, path resolution from nested cwds, kind classification, and the refuse-to-guess guardstests/test_mcp.py— 14 new tests: unconfigured server boots, all 14 tools registered with intact schemas, every tool returns the actionable message, no per-table resources, env-var configuration, dialect refusalmake pre-commitclean;tyback to its 52-diagnostic baselineNoneand 14 tools still register; missing dialect refuses with guidance;clgraph.tomlwith a dialect tracesstaging.users.email→raw.users.emailDocs
README MCP section rewritten (it published the now-removed
python -m clgraph.mcp --pipelineinvocation and the old Desktop config), plus CHANGELOG entries. The docs-site submodule PR and the remaining pages come with step 7.Next
Step 2 — A6 + A7,
clgraph detectandclgraph init, which is where the dialect question actually gets asked.