feat: erd-studio-mcp — read-only MCP server#45
Merged
Conversation
Adds "open source" language to the pitch and footer. The repo was already public + MIT, but the README didn't say so in words — now it does, with a "View source" link in the footer for discoverability. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Adds a Model Context Protocol server at mcp-server/ that gives Claude,
Cursor, Continue, Zed, etc. read-only access to a dbt project's ERD
Studio semantic model.
Architecture:
- New package mcp-server/, published independently as erd-studio-mcp
- Reuses existing pure-Node services (DomainService, LogicalModelService,
ManifestService) — no refactoring needed; those services were already
isolated from vscode APIs
- stdio transport via @modelcontextprotocol/sdk
- One file per tool, thin wrappers around the services
- esbuild bundles index.js + manifestWorker.js with ESM __dirname polyfill
so the worker_threads spawn path resolves correctly
Tools (v1, all read-only, all idempotent):
- list_domains — ERDs grouped by layer
- read_domain — full domain incl. models, columns, relationships,
cardinality, rationale
- list_models — all logical models from logical-models/*.yml
- read_model — one logical model with column-level metadata
- list_manifest_models — what dbt actually built, from target/manifest.json,
including unique/relationship test coverage
Mutation tools (propose_model_change, apply_sync_plan) deferred to v2.
Verified end-to-end via mcp-server/test-smoke.mjs against
test/fixtures/dbt-project — initialize handshake + all 5 tool calls
return expected data.
Install: `npx erd-studio-mcp` or `claude mcp add erd-studio -- npx -y erd-studio-mcp`
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The MCP server now explicitly signals it is read-only and points users to the ERD Studio VS Code extension (which ships an AI coding skill) for any write/design workflow. The two are complementary distribution paths, not redundant: the skill is deeper for Claude Code users; the MCP is broader for Cursor/Continue/Zed/Claude Desktop and discoverability via the MCP registry. Changes: - New tool: get_editor_setup returns canonical install commands + marketplace link. AI is instructed to call this when the user asks about editing/designing/building. - Server instructions block now leads with "READ-ONLY by design" and the extension path. - list_domains / list_models gracefully return empty result + a `tip` field when erd-studio/ doesn't exist, instead of erroring on fs.readdir. Same friendly path on read_domain / read_model (throw with the tip in the error message). - Smoke test extended: verifies get_editor_setup returns the marketplace link, and verifies an uninitialized project returns the install tip. - README rewritten to lead with the read-only + extension positioning, with a clear "pick the right tool" table. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
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.
Summary
Adds an MCP (Model Context Protocol) server at
mcp-server/that gives Claude, Cursor, Continue, Zed, Claude Desktop, or any MCP-compatible AI client read-only access to a dbt project's ERD Studio semantic model.The MCP is intentionally read-only. For write/design workflows (creating ERDs, adding models, drawing relationships, generating dbt SQL), the AI is instructed to point users at the VS Code extension + its bundled skill — which provides deeper integration (multi-file edits, refactor-style changes) than atomic MCP tool calls could.
The two distribution paths are complementary:
Commits
b599e5ddocs: mark project as explicitly open source4e65959feat: add MCP server (erd-studio-mcp v0.1.0)2a3037ffeat(mcp-server): position MCP as read-only complement to the extensionWhat's in this PR
New package
mcp-server/(16 files, ~2700 lines)package.json— published independently aserd-studio-mcpon npmsrc/index.ts— McpServer with stdio transport, instructions block leading with "READ-ONLY by design"src/services.ts— reuses parentDomainService,LogicalModelService,ManifestServicedirectly (these were already pure-Node, no refactor needed)src/lib/setup.ts— extension marketplace URL + canonical "not initialized" tipsrc/tools/*.ts— one file per toolTools (6 total, all read-only)
list_domainsread_domainlist_modelserd-studio/logical-models/*.ymlread_modellist_manifest_modelstarget/manifest.jsonwith test coverageget_editor_setupUX details
erd-studio/doesn't exist: list-tools return empty result +tipfield pointing at the marketplace; read-tools throw the same tip. The AI naturally surfaces the install path to the user — no scary errors.instructionsblock explicitly says READ-ONLY and tells the AI to recommend the extension for edits.Build
esbuild bundles
index.js(~150KB) +manifestWorker.js(~6KB) with ESM__dirnamepolyfill so theworker_threadsspawn resolves correctly.Tested
mcp-server/test-smoke.mjsexercises the full JSON-RPC protocol againsttest/fixtures/dbt-project:Test plan
mcp-server/src/tools/mcp-server/src/index.ts— these are loaded into AI context by every MCP clientmcp-server/README.md— what users see on npm + the GitHub package pagecd mcp-server && node test-smoke.mjslocallyOnce merged: I'll
npm publishfrommcp-server/, then open PRs tomodelcontextprotocol/serversandpunkpeye/awesome-mcp-serversto register the package.🤖 Generated with Claude Code