MCP Builder
Build one MCP-only connector package on the SDK's components. A connector depends on
scion-sdk[mcp]>=0.9.1,<0.10 and nothing else from the agent ecosystem: no
agent server, no LLM client, no provider entry points. The connector holds only what
is specific to one external system; the SDK and the shared pipelines own the rest.
Use current main revisions of
scion-sdk and
pipelines as the authority. Record the
revisions you read.
Scaffold a connector
python3 scripts/scaffold_connector.py example-mcp --output-dir /path/to/output
One command writes the whole project: the repository, images/<fleet>/,
services/<fleet>/k8s/manifests.yaml and onboarding/<fleet>/ (workspace and
arbora entries). Options:
--wrap-mcp <url-or-command>: wrap an existing MCP server. The SDK upstream
registry serves its typed tools as <namespace>_<tool>; the generated
governance.py adds write approval, a scope allow list (--scope-arg),
typed refusals and audit. The upstream URL goes to the service manifest only.
--openapi <spec>: record the OpenAPI source of the Api operations.
--deploy-profile <yml>: site values (registry, domain, namespace, secret
store, CI include). The default profile names no real host.
Output is deterministic (no date, user or host name). scaffold_connector.py is the
only generator.
example-mcp/
pyproject.toml name, version (only here), one SDK dependency, one entry point
README.md AGENTS.md connector section + Release section (bump first, tag last)
.pre-commit-config.yaml the pipelines reference config (connector-standard, secrets, spec, dependency-readiness)
.github/spec-dashboard.json connector-owned source selection for the shared dashboard
.github/workflows/pipeline.yml python_pipeline (connector) + container_pipeline (render_connector)
.github/workflows/connector-pr.yml shared PR gates
.github/workflows/pages.yml dashboard Pages caller + workflow_dispatch (theme opt-in after canonical sync)
pages/index.md minimal source for the shared Pages workflow
example_mcp/__init__.py connector = Connector(api=Api, get_client=get_client, instructions=...)
example_mcp/__main__.py from scion_sdk import run; run()
example_mcp/api_client.py class Api: one public method per API operation
example_mcp/auth.py client_factory(url_env=, auth=, tls=, delegation=)
example_mcp/connector_sources.py SOURCES = (source_meta(tool=...), ...)
example_mcp/prompts/*.json fastmcp prompts (title, tags, meta)
example_mcp/skills/<name>/SKILL.md one connector operation skill
example_mcp/skills/<fleet>-development/SKILL.md repository development contract
example_mcp/ontology/<domain>.ttl classes extend an EG core class
.specify/memory/constitution.md inherits the organization constitution; connector articles
specs/README.md specs/<CONN-ID>/{spec,plan,requirements,tasks,test-spec}.md (status computed, never committed)
tests/test_api_client.py tests of the connector's own client logic only
The scaffold writes only connector-owned delivery callers and content. The reusable
Pages workflow, dashboard renderer, hook implementations, release jobs, container
files, attestations and shapes remain owned by pipelines or the SDK. Shared theme
assets are intentionally not generated: the Pages caller leaves shared_theme_enabled
off until a pinned pipelines checkout generates the canonical files with
scripts/sync_mkdocs_theme.py sync. Do not add
mcp_server.py, _version.py, .bumpversion.cfg, docker/ files,
certification.json, a shapes file, mcp_config.json, conftest.py, kg_ingest.py
boilerplate or copies of SDK tests: the SDK and pipelines own them, and everything
the connector offers is served over MCP.
How to build each part
- Tools: one per API operation. Each HTTP method on each endpoint is one public
method of
Api; the SDK serves one tool per method, named <prefix>_<method>
(Connector(tool_prefix=...) overrides the prefix). The verb in the method docstring
(GET /items/{id}: ...) sets the annotations: GET is read-only, PUT and DELETE are
idempotent, DELETE is destructive and asks the caller to confirm. Never condense
operations into action or params_json dispatch tools. Tools that are not client
methods go in <pkg>/tools.py as register_<tag>_tools(mcp), or in
Connector(extra_registrations=...). Check the served count against the API
operation count with scripts/check_tool_parity.py.
- Data sources: declared data.
connector_sources.py holds SOURCES built with
source_meta(tool=..., source_id=..., record_type=..., id_field=..., fields={...}), plus optional FIELD_SETS and SCHEMA_VERSION. Use for_each on a
source to fan out per parent record. The SDK builds the declaration with
load_declaration and serves it as connector://resources. Write no manifest file
and no declaration() function. Set record_type to the ontology class name.
- Ontology.
ontology/<domain>.ttl in the shared : namespace. Every class gets
rdfs:subClassOf an epistemic-graph core class (the scaffold uses :Concept; narrow
it when a core class fits) and an object property to a core class. Never
owl:imports the core ontology. Shapes and attestations are generated at release.
Check with pipelines-hook connector-ontology-map graph-check.
- Prompts and skills. Prompts are
prompts/<name>.json, served as fastmcp prompts
with title (identity.role), tags and _meta (role, topic, version, serves).
Skills are skills/<name>/SKILL.md directories served by the SDK skills provider.
- Use SDK components, never your own. Auth, TLS, delegation and credential
rotation:
client_factory with one declaration (Bearer, ApiKey, Basic,
ClientCredentials, RefreshToken, SessionLogin, NoAuth). Paging:
PaginationIterator. Limits: RateLimiter. GraphQL: GraphQLClient
(scion-sdk[graphql]). Vector search: the SDK vector extra. Optional
dependencies are SDK extras only. Do not pin requests, httpx or gql.
- Server. The
scion_sdk.connector entry point
(<fleet> = "<pkg>:connector") and the console script
<fleet> = "scion_sdk.cli:serve" start the server: health route,
middleware, transports, content, metadata version. Write no server bootstrap.
- Tests. Write tests of your own client logic only. The SDK pytest plugin
generates the fleet-name, content, ontology, source, startup and version tests in
any environment that installs the SDK. Copy none of them; add no
conftest.py.
- Version and release. The version lives in
pyproject.toml only; read it with
importlib.metadata. Pipelines bumps it, renders the container files, and
generates the ontology shapes at build time. The shared workflows publish to PyPI
and Docker Hub.
Check a new connector with connector-name --strict, the connector-standard file
check and connector-ontology-map graph-check before the first push.
Contracts
- Preserve 100% of the supported source operation catalog across API and MCP surfaces.
Require deterministic inventory, schema and dispatch parity; distinguish mocked
transport coverage from live endpoint checks. Do not replace a full integration
with placeholder or selected operations.
- Keep vendor requests and pagination in the API client. MCP tools validate inputs and
use SDK registration; they do not bypass authorization or effect controls.
- Use typed SDK ingestion. Source adapters and write-back ports require their
applicable conformance checks.
- Preserve user scope, authorization and credential-reference boundaries.
Scaffolding does not authorize external writes, deployment, credential creation,
publication or changes to live services.
- Keep generated files environment-neutral. Never generate credentials, private
endpoints, personal identities, a committed .env or a TLS-verification bypass.
Load the relevant reference
- Backend contracts: API schemas, authentication,
pagination and errors; CLI argument vectors, execution bounds and proof cases.
- Connector contracts: SDK ownership, manifests,
ingestion/effects, packaging, quality gates and source authorities.
- Python server: factory, tools and explicit content.
- Context helpers: confirmation, progress and safe logging.
- File parity: the generated tree and who owns every other file.
- Documentation readiness: bounded source-only
discovery, ownership manifests, public docs and served-surface checks.
- MCP design: tool boundaries and transport choices.
- OpenAPI and publication: provider conversion and
publishing a validated local tree to a new normal GitHub repository.
- OpenAPI readiness: named discovery budgets and
hash-bound provider evidence; separate from transport and live acceptance.
- Evaluation: optional read-only task evaluation with the
existing model harness; it does not replace static and contract checks.
Completion evidence
Validate frontmatter and local links, generator rerun behavior and a small isolated
generated project. Check Python syntax, metadata, explicit content/tool registration,
schema/manifest agreement and applicable source/effect contracts without live calls.
Run scripts/check_connector_contract.py <root> --package <pkg> (it rejects any
import of, or dependency on, the retired control-plane package). Run normal
lint and pre-commit gates in an existing environment; report unavailable checks
accurately. Do not install native toolchains or broaden dependencies for unrelated
checks.
For reproducible output, pass --generation-date YYYY-MM-DD or set SOURCE_DATE_EPOCH (UTC Unix seconds). The explicit date wins; otherwise generation uses today's UTC date. Generation dates never establish delivery or release evidence.
1---2name: mcp-builder-23domain: agent-tools4skill_type: skill5description: >-6 Build or update an SDK-only MCP connector package: it depends on7 scion-sdk alone (never the agent control plane) and follows shared8 pipelines standards. Use when wrapping REST or GraphQL APIs from schemas or9 documentation, exposing a CLI through MCP, or updating connector registration,10 package content, ingestion contracts, and repository scaffolding.11license: MIT12tags: [mcp, development, protocol, tools, api, cli]13metadata:14 source: https://skillmd.com/skills/knuckles-team/mcp-builder-215 version: '1.6.0'16 author: Genius17---1819# MCP Builder2021Build one MCP-only connector package on the SDK's components. A connector depends on22`scion-sdk[mcp]>=0.9.1,<0.10` and nothing else from the agent ecosystem: no23agent server, no LLM client, no provider entry points. The connector holds only what24is specific to one external system; the SDK and the shared pipelines own the rest.2526Use current main revisions of27[scion-sdk](https://github.com/Knuckles-Team/scion-sdk) and28[pipelines](https://github.com/Knuckles-Team/pipelines) as the authority. Record the29revisions you read.3031## Scaffold a connector3233 python3 scripts/scaffold_connector.py example-mcp --output-dir /path/to/output3435One command writes the whole project: the repository, `images/<fleet>/`,36`services/<fleet>/k8s/manifests.yaml` and `onboarding/<fleet>/` (workspace and37arbora entries). Options:3839- `--wrap-mcp <url-or-command>`: wrap an existing MCP server. The SDK upstream40 registry serves its typed tools as `<namespace>_<tool>`; the generated41 `governance.py` adds write approval, a scope allow list (`--scope-arg`),42 typed refusals and audit. The upstream URL goes to the service manifest only.43- `--openapi <spec>`: record the OpenAPI source of the `Api` operations.44- `--deploy-profile <yml>`: site values (registry, domain, namespace, secret45 store, CI include). The default profile names no real host.4647Output is deterministic (no date, user or host name). `scaffold_connector.py` is the48only generator.4950 example-mcp/51 pyproject.toml name, version (only here), one SDK dependency, one entry point52 README.md AGENTS.md connector section + Release section (bump first, tag last)53 .pre-commit-config.yaml the pipelines reference config (connector-standard, secrets, spec, dependency-readiness)54 .github/spec-dashboard.json connector-owned source selection for the shared dashboard55 .github/workflows/pipeline.yml python_pipeline (connector) + container_pipeline (render_connector)56 .github/workflows/connector-pr.yml shared PR gates57 .github/workflows/pages.yml dashboard Pages caller + workflow_dispatch (theme opt-in after canonical sync)58 pages/index.md minimal source for the shared Pages workflow59 example_mcp/__init__.py connector = Connector(api=Api, get_client=get_client, instructions=...)60 example_mcp/__main__.py from scion_sdk import run; run()61 example_mcp/api_client.py class Api: one public method per API operation62 example_mcp/auth.py client_factory(url_env=, auth=, tls=, delegation=)63 example_mcp/connector_sources.py SOURCES = (source_meta(tool=...), ...)64 example_mcp/prompts/*.json fastmcp prompts (title, tags, meta)65 example_mcp/skills/<name>/SKILL.md one connector operation skill66 example_mcp/skills/<fleet>-development/SKILL.md repository development contract67 example_mcp/ontology/<domain>.ttl classes extend an EG core class68 .specify/memory/constitution.md inherits the organization constitution; connector articles69 specs/README.md specs/<CONN-ID>/{spec,plan,requirements,tasks,test-spec}.md (status computed, never committed)70 tests/test_api_client.py tests of the connector's own client logic only7172The scaffold writes only connector-owned delivery callers and content. The reusable73Pages workflow, dashboard renderer, hook implementations, release jobs, container74files, attestations and shapes remain owned by `pipelines` or the SDK. Shared theme75assets are intentionally not generated: the Pages caller leaves `shared_theme_enabled`76off until a pinned pipelines checkout generates the canonical files with77`scripts/sync_mkdocs_theme.py sync`. Do not add78`mcp_server.py`, `_version.py`, `.bumpversion.cfg`, `docker/` files,79`certification.json`, a shapes file, `mcp_config.json`, `conftest.py`, `kg_ingest.py`80boilerplate or copies of SDK tests: the SDK and pipelines own them, and everything81the connector offers is served over MCP.8283## How to build each part84851. **Tools: one per API operation.** Each HTTP method on each endpoint is one public86 method of `Api`; the SDK serves one tool per method, named `<prefix>_<method>`87 (`Connector(tool_prefix=...)` overrides the prefix). The verb in the method docstring88 (`GET /items/{id}: ...`) sets the annotations: GET is read-only, PUT and DELETE are89 idempotent, DELETE is destructive and asks the caller to confirm. Never condense90 operations into `action` or `params_json` dispatch tools. Tools that are not client91 methods go in `<pkg>/tools.py` as `register_<tag>_tools(mcp)`, or in92 `Connector(extra_registrations=...)`. Check the served count against the API93 operation count with `scripts/check_tool_parity.py`.942. **Data sources: declared data.** `connector_sources.py` holds `SOURCES` built with95 `source_meta(tool=..., source_id=..., record_type=..., id_field=..., ontology_class=...,96 fields={...})`, plus optional `FIELD_SETS` and `SCHEMA_VERSION`. Use `for_each` on a97 source to fan out per parent record. The SDK builds the declaration with98 `load_declaration` and serves it as `connector://resources`. Write no manifest file99 and no `declaration()` function. Set `record_type` to the ontology class name.1003. **Ontology.** `ontology/<domain>.ttl` in the shared `:` namespace. Every class gets101 `rdfs:subClassOf` an epistemic-graph core class (the scaffold uses `:Concept`; narrow102 it when a core class fits) and an object property to a core class. Never103 `owl:imports` the core ontology. Shapes and attestations are generated at release.104 Check with `pipelines-hook connector-ontology-map graph-check`.1054. **Prompts and skills.** Prompts are `prompts/<name>.json`, served as fastmcp prompts106 with title (`identity.role`), tags and `_meta` (role, topic, version, `serves`).107 Skills are `skills/<name>/SKILL.md` directories served by the SDK skills provider.1085. **Use SDK components, never your own.** Auth, TLS, delegation and credential109 rotation: `client_factory` with one declaration (`Bearer`, `ApiKey`, `Basic`,110 `ClientCredentials`, `RefreshToken`, `SessionLogin`, `NoAuth`). Paging:111 `PaginationIterator`. Limits: `RateLimiter`. GraphQL: `GraphQLClient`112 (`scion-sdk[graphql]`). Vector search: the SDK `vector` extra. Optional113 dependencies are SDK extras only. Do not pin `requests`, `httpx` or `gql`.1146. **Server.** The `scion_sdk.connector` entry point115 (`<fleet> = "<pkg>:connector"`) and the console script116 `<fleet> = "scion_sdk.cli:serve"` start the server: health route,117 middleware, transports, content, metadata version. Write no server bootstrap.1187. **Tests.** Write tests of your own client logic only. The SDK pytest plugin119 generates the fleet-name, content, ontology, source, startup and version tests in120 any environment that installs the SDK. Copy none of them; add no `conftest.py`.1218. **Version and release.** The version lives in `pyproject.toml` only; read it with122 `importlib.metadata`. Pipelines bumps it, renders the container files, and123 generates the ontology shapes at build time. The shared workflows publish to PyPI124 and Docker Hub.125 Check a new connector with `connector-name --strict`, the `connector-standard` file126 check and `connector-ontology-map graph-check` before the first push.127128## Contracts129130- Preserve 100% of the supported source operation catalog across API and MCP surfaces.131 Require deterministic inventory, schema and dispatch parity; distinguish mocked132 transport coverage from live endpoint checks. Do not replace a full integration133 with placeholder or selected operations.134- Keep vendor requests and pagination in the API client. MCP tools validate inputs and135 use SDK registration; they do not bypass authorization or effect controls.136- Use typed SDK ingestion. Source adapters and write-back ports require their137 applicable conformance checks.138- Preserve user scope, authorization and credential-reference boundaries.139 Scaffolding does not authorize external writes, deployment, credential creation,140 publication or changes to live services.141- Keep generated files environment-neutral. Never generate credentials, private142 endpoints, personal identities, a committed .env or a TLS-verification bypass.143144## Load the relevant reference145146- [Backend contracts](reference/backend_contracts.md): API schemas, authentication,147 pagination and errors; CLI argument vectors, execution bounds and proof cases.148- [Connector contracts](reference/connector_contracts.md): SDK ownership, manifests,149 ingestion/effects, packaging, quality gates and source authorities.150- [Python server](reference/python_mcp_server.md): factory, tools and explicit content.151- [Context helpers](reference/ctx_helpers.md): confirmation, progress and safe logging.152- [File parity](PARITY_MANIFEST.md): the generated tree and who owns every other file.153- [Documentation readiness](DOCUMENTATION_STANDARD_VNEXT.md): bounded source-only154 discovery, ownership manifests, public docs and served-surface checks.155- [MCP design](reference/mcp_best_practices.md): tool boundaries and transport choices.156- [OpenAPI and publication](reference/openapi_bootstrap.md): provider conversion and157 publishing a validated local tree to a new normal GitHub repository.158- [OpenAPI readiness](reference/openapi_readiness.md): named discovery budgets and159 hash-bound provider evidence; separate from transport and live acceptance.160- [Evaluation](reference/evaluation.md): optional read-only task evaluation with the161 existing model harness; it does not replace static and contract checks.162163## Completion evidence164165Validate frontmatter and local links, generator rerun behavior and a small isolated166generated project. Check Python syntax, metadata, explicit content/tool registration,167schema/manifest agreement and applicable source/effect contracts without live calls.168Run `scripts/check_connector_contract.py <root> --package <pkg>` (it rejects any169import of, or dependency on, the retired control-plane package). Run normal170lint and pre-commit gates in an existing environment; report unavailable checks171accurately. Do not install native toolchains or broaden dependencies for unrelated172checks.173174For reproducible output, pass `--generation-date YYYY-MM-DD` or set `SOURCE_DATE_EPOCH` (UTC Unix seconds). The explicit date wins; otherwise generation uses today's UTC date. Generation dates never establish delivery or release evidence.