MCP 服务器

known-path

A lightweight MCP server that activates only trusted catalog assets for a data job, performs trust checks, and generates SQL artifacts.

README

Light only the trusted catalog assets for a data job — then leave the route behind.

<a href="#quickstart">Quickstart</a> · <a href="#how-it-works">How it works</a> · <a href="#demo">Demo</a> · <a href="#mcp--agents">MCP & agents</a> · <a href="#hackathon">Hackathon</a> · <a href="docs/HACKATHON.md">Compliance</a>

Why this exists

Data catalogs already know which table is canonical, which is deprecated, and who owns it.
Agents still thrash search and join the wrong revenue_* table.

known-path is a small activation layer on top of that catalog truth:

Load a short route sheet for the job
Light only the few assets that matter
Stop if trust is red (no invented replacements)
Emit SQL you could open a PR with
Write a route note so the next run starts smarter

Built for the DataHub Agent Hackathon — tracks Metadata-Aware Code Generation and Agents That Do Real Work.

How it works

flowchart LR
  A[Job intent] --> B[Route sheet]
  B --> C[Score & shortlist]
  C --> D{Trust check}
  D -->|red| E[Fail closed<br/>leave block note]
  D -->|green| F[Fetch detail<br/>budgeted]
  F --> G[SQL artifact]
  G --> H[Write route note<br/>back to catalog/files]
  subgraph Catalog truth
    DH[(DataHub GMS<br/>or fixture stand-in)]
  end
  C -.-> DH
  F -.-> DH
  H -.-> DH

Mode	Behavior
baseline	Naive name thrash — more fetches, often lights `finance.revenue_old`
known-path	Route sheet + trust — lights canonical + region only
blocked	Forces red trust — stops, does not invent a table

This is not a second catalog, not a lineage UI, and not “dump all metadata into the prompt.”

Quickstart

git clone https://github.com/SeraKah-1/known-path.git
cd known-path
python -m venv .venv && source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -e ".[dev]"

kp doctor
kp demo

Artifacts land in:

examples/baseline_wrong.sql
examples/revenue_by_region.sql
examples/runs/last_*.json
examples/runs/writeback_route_note.md

Optional live DataHub

export DATAHUB_GMS_URL=http://localhost:8080
export DATAHUB_GMS_TOKEN=your_token
kp doctor

Web workbench (enterprise UI)

No extra deps (stdlib server). Every button runs the real CLI (python -m known_path.cli …).

kp web
# or:
python -m known_path.webapp --host 0.0.0.0 --port 8088
# open http://127.0.0.1:8088

Panel	What you get
Job intent + CTAs	Baseline / Known path / Fail closed / Full demo
Activation graph	SVG nodes lit from last CLI plan
Fetch comparison	Honest shared-axis bars (baseline vs known-path vs blocked)
Catalog table	demo-finance assets + usage bars
Agent terminal	Type `run known-path`, `demo`, `doctor` — bridged to CLI

kp dataset   # list assets + path

UX notes: docs/UX_AND_RESOURCES.md

Demo

kp demo

Expected story:

Step	Result
Baseline	Higher fetch count; trap table can activate
Known path	`finance.revenue_canonical` + `dim.region`; fewer fetches
Blocked	Status `BLOCKED_TRUST`; no SQL invention

kp run --mode baseline  -i "revenue by region last quarter"
kp run --mode known-path -i "revenue by region last quarter"
kp run --mode blocked   -i "revenue by region last quarter"

Sample SQL (generated):

-- known-path generated SQL
-- job: job.revenue_by_region_quarter
-- fact_urn: urn:li:dataset:(urn:li:dataPlatform:snowflake,finance.revenue_canonical,PROD)
SELECT
  d.region_name AS region,
  SUM(f.revenue_amount) AS revenue
FROM finance.revenue_canonical AS f
JOIN dim.region AS d
  ON f.region_id = d.region_id
...

MCP & agents

Install MCP extra and run the server:

pip install -e ".[mcp]"
python -m known_path.mcp_server

Tools: match_job · activate · ping_required · commit_route · explain_last_run

Skill package: skills/known-path/SKILL.md — workflow instructions agents load on demand (pairs with tools, does not replace them).

Example Cursor / Claude MCP snippet:

{
  "mcpServers": {
    "known-path": {
      "command": "python",
      "args": ["-m", "known_path.mcp_server"],
      "cwd": "/path/to/known-path"
    }
  }
}

Project layout

known-path/
├── assets/                 # logo + diagrams
├── cards/                  # route sheets (YAML)
├── datasets/demo-finance/  # demo catalog.json + CSV samples
├── docs/HACKATHON.md       # Devpost compliance map
├── docs/demo-recording/    # recorded demo video + evidence
├── examples/               # SQL + run records
├── skills/known-path/      # agent skill
├── src/known_path/         # library + CLI + MCP + web
├── apps/web/               # optional FastAPI wrapper
└── tests/                  # real scoring/activation tests