wicked-garden-mcp-scaffold
Skill9 starsChanged 7 months agoMITView on GitHub
Build a new MCP server that wicked-crew's broker can register and govern: scaffold a TypeScript server (fastmcp, OpenTelemetry, loglayer; the default) or a zero-dependency one-file stdio server (Node or Python), add tools with honest annotations, keep the one secret in the environment the broker injects, then probe it — initialize + tools/list, with each tool's class (read / write / destructive) derived exactly as the broker derives it.
- Reads credentials
- Installs packages
In this repository142 other files it gives its agents.
- AGENTS.mdAGENTS.md
- .claude/CLAUDE.mdCLAUDE.md
- plugin-json-schemaSkill
- readme-style-guideSkill
- releaseSkill
- scaffoldSkill
- wicked-garden-agentic-agentic-patternsSkill
- wicked-garden-agentic-architectSkill
- wicked-garden-agentic-context-engineeringSkill
- wicked-garden-agentic-frameworksSkill
- wicked-garden-agentic-performance-analystSkill
- wicked-garden-agentic-review-methodologySkill
- wicked-garden-agentic-safety-reviewerSkill
- wicked-garden-agenticSkill
- wicked-garden-agentic-trust-and-safetySkill
- wicked-garden-appsSkill
- wicked-garden-archetypeSkill
- wicked-garden-build-guideSkill
- wicked-garden-classifySkill
- wicked-garden-coreSkill
- wicked-garden-data-engineerSkill
- wicked-garden-dataSkill
- wicked-garden-deliberateSkill
- wicked-garden-demoSkill
- wicked-garden-domain-coverageSkill
- wicked-garden-domain-extractorSkill
- wicked-garden-domain-modelerSkill
- wicked-garden-domainSkill
- wicked-garden-draftSkill
- wicked-garden-editor-scaffoldSkill
- wicked-garden-engineering-api-documentarianSkill
- wicked-garden-engineering-architectureSkill
- wicked-garden-engineering-backendSkill
- wicked-garden-engineering-debuggingSkill
- wicked-garden-engineering-docsSkill
- wicked-garden-engineering-frontendSkill
- wicked-garden-engineering-integrationSkill
- wicked-garden-engineering-large-scale-migrationSkill
- wicked-garden-engineering-migration-engineerSkill
- wicked-garden-engineering-patchSkill
- wicked-garden-engineeringSkill
- wicked-garden-engineering-solution-architectSkill
- wicked-garden-engineering-system-designSkill
- wicked-garden-engineering-unit-test-qualitySkill
- wicked-garden-governed-workerSkill
- wicked-garden-groundSkill
- wicked-garden-jam-brainstorm-facilitatorSkill
- wicked-garden-jam-councilSkill
- wicked-garden-jamSkill
- wicked-garden-learnSkill
- wicked-garden-mcpSkill
- wicked-garden-mem-captureSkill
- wicked-garden-mem-ingestSkill
- wicked-garden-memSkill
- wicked-garden-personaSkill
- wicked-garden-platform-auditSkill
- wicked-garden-platform-compliance-officerSkill
- wicked-garden-platform-complianceSkill
- wicked-garden-platform-errorsSkill
- wicked-garden-platform-gate-benchmark-rebaselineSkill
- The first 60 shown.
The file
We split this skill into the rules it gives an agent
9 rules. About 0 are common, 5 are distinctive, and 4 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈5
Distinctive · estimate
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 35
If none of these is available, or Python 3 is missing, skip the script-backed step, say so, and follow the manual alternative where one is …
- Distinctive: line 152
Keep schemas stable. A changed tool schema puts that tool back to unregistered until the operator previews and approves it again.
- Very specific: line 155
Secrets: Read a credential from an environment variable (for example ACME_API_TOKEN).
- Very specific: line 183
Do not stop at ok: true: check every tool's class is the one you meant, and clear every warning.
- Very specific: line 186
Manual alternative: run the server command, paste these two lines on its stdin and check that two replies come back, with tools in the …
- Distinctive: line 263
After approval the run mode decides: *Gate every step* asks on every write call.
- Distinctive: line 276
Write the server into the run's deliverable directory with step 1.
- Distinctive: line 278
Before you add a layer the template does not have (an HTTP or REST surface, an OpenAPI description, auth, sessions), check what the chosen …
- Very specific: line 287
Do not register the server, add it to any CLI's MCP configuration, or start it outside the probe — outside the mcp-server workflow's …
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
MCP scaffold
Scaffold → generate tools from an OpenAPI document (or write them) → probe → install for running (or hand over for registration). The server you build is an upstream of the wicked-crew broker: the broker holds its connection and its secrets, judges every call through steering policy, and records every call. Your server only has to speak MCP over stdio and describe its tools honestly.
Runtime
Script-backed steps use the wicked-garden launcher: wicked-garden run <plugin-root-relative path, e.g. scripts/…> [args]. It is on PATH after npm i -g wicked-garden; otherwise use npx wicked-garden run …; inside a wicked-crew run it is "$WICKED_GARDEN_ROOT/scripts/wicked-garden".
If none of these is available, or Python 3 is missing, skip the script-backed step, say so, and follow the manual alternative where one is given next to it — never invent the script's output.
Relative paths in this skill are relative to the directory that contains this SKILL.md.
1. Scaffold
wicked-garden run scripts/mcp/scaffold.py --name <server-name> [--lang typescript|node|python] --out <dir>--namebecomes the registry key and themcp:<server>/<tool>subject segment: lowercase letters, digits and-, starting with a letter, at most 64 characters. Its upper-cased form (-→_) prefixes the server's environment variables:acme-notes→ACME_NOTES_TOKEN.--lang typescriptis the default: a whole project fromassets/typescript/— fastmcp on Node >= 22, loglayer, OpenTelemetry,mcp-server.config.json,tools.json, a stdio conformance smoke and a contract-test shape undernpm test.--outmay already exist (a repo root or a subdirectory of one), but every file the scaffold would write must be absent: it refuses naming the first collision and writes nothing. Thennpm install && npm run build.--lang node|pythonwrites one dependency-free file (<dir>/server.mjsor<dir>/server.py) — for a one-file server with no build step. Same no-overwrite rule.- It prints JSON with the written path, the run command, the probe command and (TypeScript) the secret variable's NAME.
- Manual alternative: copy
assets/typescript/(renaminggitignore→.gitignoreandenv.example→.env.example),assets/node/server.mjsorassets/python/server.pyinto<dir>, replacing every__SERVER_NAME__with the server name,__SERVER_ENV__with its upper-cased form and__YEAR__with the year.
The one-file templates answer initialize (negotiating the protocol version), ping,
tools/list and tools/call, ignore notifications, and ship two example tools: echo
(read) and counter_increment (write). The TypeScript template registers what tools.json
holds, and its example echo (read) only while tools.json is empty. Replace the examples
with your own.
2. Generate tools from an OpenAPI document (openapi)
wicked-garden run scripts/mcp/openapi.py --name <key> --base-url <url> (--spec <file> | --spec-url <url>) [--operations a,b] --out <dir> [--crew-url <origin>]The conversion service is wicked-crew's (POST /api/v1/mcp/servers/preview, kind rest) —
the same one studio's Wrap an API uses, so there is one OpenAPI reading in the platform.
The daemon origin is --crew-url, else $WICKED_CREW_URL (crew sets it to its own URL in
every governed unit). There is no port default: never type a port — a guessed one can
be another daemon's registry. With neither set the scripts exit 2 naming the remedy. One tool per operation; the class comes from the method
(GET/HEAD/OPTIONS read, POST write, PUT/PATCH/DELETE destructive); 1 MB and 10 s bounds;
external $refs are not followed.
- It writes
<dir>/tools.jsonas{"source": {specUrl | specFile, baseUrl, convertedAt}, "tools": [{name, description, inputSchema, annotations, class, rest}], "skipped": [...]}and setsbaseUrlin<dir>/mcp-server.config.json. It refuses to overwrite atools.jsonthat is not the empty template. - A local
--specis sent as JSON (YAML only when PyYAML is installed; otherwise it exits 2 telling you to pass--spec-url). - It never reads or sends a secret, and prints one JSON summary: tool count, classes,
skipped operations. Report the
skippedlist; each is an operation with no tool. - No daemon answering → exit 2: the conversion service is the wicked-crew daemon; write the tools by hand (branch B). Never invent tools.
3. Add tools: the contract
TypeScript (the skeleton's contract):
- Register every tool through
defineTool(server, config, tool)(src/tools/registry.ts). It wrapsexecutein amcp.tool.callspan, a request-scoped child logger (getLogger()inside the handler), themcp.tool.calls/mcp.tool.duration/mcp.tool.errorsinstruments, the per-tool rate limit (rateLimitPerMin) andcanAccess: requireSession. ThrowUserErrorfor a failure the caller should see — it comes back asisError. - Generated tools (branch A) come from
tools.json:src/tools/generated.tsregisters each entry with its JSON Schema (wrapped in fastmcp'sjsonSchemaAdapter— fastmcp rejects a raw JSON Schema and the server would not start) and the annotations its class implies; an upstream error reaches the caller bounded, with the credential scrubbed; calls go throughsrc/rest.ts— pinned tobaseUrl, allowlisted arguments only, no redirects, auth and hop-by-hop headers never settable by an argument. Hand-written tools (branch B) followsrc/tools/example.ts: a zod schema validated before the handler runs, honest annotations. - One secret variable,
<SERVER>_TOKEN(the bearer token, API key, basic password or OAuth2 client secret, asauth.schemesays). Every non-secret parameter — scheme, header, basic user, token URL, scopes, client id, base URL, rate limit — is committed inmcp-server.config.json. A missing secret fails at startup naming the variable. One variable is the contract because crew's broker and registry inject exactly one. - A query-parameter API key (an OpenAPI
apiKeyscheme within: query) is config, not a hand extension:"auth": {"scheme": "api-key", "queryParam": "<name>", ...}. The server adds it to the URL after the boundary check, no argument can set it, and it is scrubbed (raw and URL-encoded) from upstream error bodies exactly like a header credential — every credential the server sends goes through one carrier,upstreamCredentials. - Logging goes to stderr only (loglayer; the console transport is bound to stderr), with trace ids stamped by the OpenTelemetry plugin and secrets redacted by name.
- Telemetry is off by default: the SDK arms its OTLP exporters only when
OTEL_EXPORTER_OTLP_ENDPOINTis set. - httpStream (
MCP_TRANSPORT=httpStream) requiresMCP_SERVER_BEARER; a request without it is refused with 401. - Copy
test/contract/example.test.tsonce per tool;npm testruns them plustest/conformance.test.ts.
Node/Python one-file servers: each tool is one entry in the TOOLS table:
description, inputSchema (JSON Schema, type: object), annotations and a handler. A
handler returns text; a bad call raises ToolError, which comes back as isError.
Every template — the rules the broker relies on:
The broker derives each tool's class from its annotations (an operator override in the registry wins), and the class decides its posture:
| Annotations | Class |
readOnlyHint: true | read |
an annotations object with readOnlyHint false or absent and destructiveHint true or absent | destructive |
an annotations object with readOnlyHint: false and destructiveHint: false | write |
no annotations object at all | write |
- Set
readOnlyHint: trueonly when the tool changes nothing anywhere: no files, no remote state, no sent messages. The operator sees these annotations in the preview and can override a class; a false read claim is found at review, not hidden by it. - Set
destructiveHint: falseonly when the tool cannot delete or overwrite anything. - Set
idempotentHint: trueonly when repeating a call is harmless, andopenWorldHint: truewhen the tool reaches a system outside the server. - Tool names: letters, digits,
_and-. No/(it splits the subject) and no__. - Keep schemas stable. A changed tool schema puts that tool back to unregistered until the operator previews and approves it again; a renamed tool is a new tool.
Secrets. Read a credential from an environment variable (for example
ACME_API_TOKEN). At registration the operator stores the value in the broker, which injects
it into the server's environment at call time and nowhere else. Never log a secret, never
return it in a result, never accept it as a tool argument, and never write it into the repo
or a config file.
stdout carries protocol frames only. Log to stderr (the template's log()); one stray
print on stdout breaks the session.
4. Probe
wicked-garden run scripts/mcp/probe.py --timeout 30 --env <SERVER>_TOKEN -- node <dir>/dist/server.js
wicked-garden run scripts/mcp/probe.py -- node <dir>/server.mjs
wicked-garden run scripts/mcp/probe.py -- python3 <dir>/server.pyThe probe starts the server with a minimal environment (PATH, HOME and the OS system and
temp variables only, so no ambient tokens) plus exactly the variables named with --env
(the TypeScript server refuses to start without its secret; a dummy value is enough to
probe), runs initialize then tools/list (following
nextCursor), and prints JSON: ok, protocolVersion, serverInfo, every tool with its
derived class, and warnings (an unannotated tool, a schema that is not an object, a /
in a name). It exits 1 with an error when the server fails to answer; the server's stderr
is never echoed — with --env, a failure lists only which of those NAMES the stderr
mentioned (stderrNames). --timeout <s> (default 10) bounds the whole probe; give the
TypeScript server 30 on a loaded host (loading its dependencies takes a few seconds).
Do not stop at ok: true: check every tool's class is the one you meant, and clear
every warning.
Manual alternative: run the server command, paste these two lines on its stdin and
check that two replies come back, with tools in the second:
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"manual","version":"1"}}}
{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}Then derive each tool's class by hand from the table in step 3.
5. Install for running (install)
wicked-garden run scripts/mcp/install.py (--from-run | --dir <server dir>) [--key <key>] [--from-npm <pkg>@<version>] [--target worker|operator] [--dry-run] [--cli all|claude,codex,opencode,antigravity,pi|none] [--crew-url <origin>] [--install-root <dir>] [--json]
wicked-garden run scripts/mcp/install.py --uninstall <key> [--target worker|operator]Installs the built TypeScript server — or updates the installed copy — idempotent by the
config's key:
- Locate:
--from-runfinds the onemcp-server.config.jsonin the run's worktree (the cwd;$WICKED_TREEis the worktree's tree id, used only when it names a directory), outsidenode_modules/dist; more or fewer than one exits 2 naming the candidates.--dirnames it. The version is the config'sversion. - Stage:
npm ci --ignore-scripts && npm run buildin the server dir, thendist/,package.json,package-lock.json,tools.jsonandmcp-server.config.jsonare copied to<root>/<key>/next/andnpm ci --omit=dev --ignore-scriptsruns there. The root is--install-root, else$WICKED_MCP_INSTALL_ROOT, else~/.wicked/mcp-servers.--from-npminstalls a published package there instead. - Smoke: the probe, passing
<SERVER>_TOKENthrough. A failure naming that variable issmoke: "pending_credential"(disclosed, not failed); any other failure exits 1 withnext/removed and nothing else touched. - Swap:
current/→previous/,next/→current/. The commandnode <root>/<key>/current/dist/server.jsnever changes across updates. - Register in crew's MCP registry with
auth: {ref: "env:<SERVER>_TOKEN"}— a reference the daemon resolves from its own environment, never a value. A daemon missing the variable answerssecret_missing: the record saysregistered: false,missing, and two remedies (export it in the daemon's environment and re-run; or studio MCP tools → Add existing with the secret, stored in the OS keychain). No daemon:registered: falsewith the reason. Re-registering the same key is the update (registered: "updated") — of THIS install only: before anything is staged, a registry entry under the key that is a different server (anotherkind, command or args — say a REST server with the same name) exits 1 naming it, with nothing written. Pick another key, or remove that server first. - CLI configs through
wicked-installer mcp upsert(never written by this script); an installer without the verb is reported asclis: "skipped: …", not failed.--target worker(the default) registers the server only in the worker seats' CLI configs under the worker home ($WICKED_WORKER_HOME, else~/.wicked-worker:claude/.claude.json,codex/config.toml,opencode/config/opencode/);--target operatoralso writes the operator's own CLI configs (~/.claude.json,~/.codex/config.toml, the opencode config), reported asoperatorClis. Only the operator choosesoperator, at the install gate.
--dry-run writes nothing (it only reads the registry for the key check) and prints ONE
JSON line, the plan the install gate shows: {"dry_run": true, "key", "choices": [{"id":
"worker" | "operator", "label", "default"?, "writes": [{"path", "what", "cli"?,
"operator_owned"}]}], "skipped": [{"cli", "why"}]} — every path absolute, each choice listing
everything it would write, the CLI rows from wicked-installer mcp upsert --dry-run. It exits
non-zero (the reason on stderr) when it cannot plan.
7. Record <root>/<key>/installed.json {key, version, source, command, args,
envNames, installedAt, registered, smoke} and print it with probe, registry and clis.
Exit 0 when staged (even with a pending credential or no daemon — both are disclosed), 1 on a staging, smoke or registry failure, 2 on bad arguments. The first use of a newly registered server still waits for the operator's approval (step 6).
6. Hand over for registration (when you do not install)
The operator registers it in studio MCP tools, Add existing: paste the run command and the secret. The preview lists every tool with its class and what each phase role and seat would be allowed, asked or denied. Tell the operator the command, the tool list with classes, and the name of the environment variable that holds the secret (never its value).
What happens after registration is policy, not your server's code:
- The first time any run uses the server, and again when a tool's schema changes, the call waits for the operator's approval, in every run mode. An approval is an audited policy edit that adds the server or tool to the approved set.
- After approval the run mode decides: Gate every step asks on every write call; Gate by risk runs reads and asks on writes; Auto runs reads and writes.
- In every mode: evaluator phases never call write or destructive tools; an unannotated tool counts as write; secrets stay in the broker; unregistered servers and tools are denied; every call is recorded, or refused if it cannot be.
- A denied call is blocked and disclosed to the worker; the unit continues.
In a governed run
You are in one when a wicked-crew phase directive or the wicked-garden-governed-worker
skill was handed to you (WICKED_RUN_ID is set). This is the studio Build a server
run. Follow wicked-garden-governed-worker, and:
- Write the server into the run's deliverable directory with step 1. Implement the tools the intent names, annotated per step 3.
- Before you add a layer the template does not have (an HTTP or REST surface, an OpenAPI
description, auth, sessions), check what the chosen stack already provides at the
version the project pins: fastmcp for the TypeScript template, the Node or Python
standard library for a one-file server. Use what it provides, and do not bring in
another framework the run did not choose. Record the check in your output: the version,
what you read, what it offers. Hand-written code that duplicates a built-in needs a
stated reason, and the review phase flags it (
wicked-garden-governed-worker, C8 and E5). - Probe it (step 4) and put the probe's JSON in your output as the evidence that it answers. A probe failure is a finding to fix, not to report as done.
- Do not register the server, add it to any CLI's MCP configuration, or start it outside
the probe — outside the
mcp-serverworkflow'sinstallphase. Do not put a secret anywhere: name the environment variable instead.
The mcp-server workflow, phase by phase:
- scope — settle what to expose, the auth scheme, the transport (stdio unless a remote
client needs httpStream) and the target directory: the root of a near-empty repo, or a
subdirectory of an existing one. A repository that is not registered must be created and
registered by the operator first — say so, do not create it. List the registry's keys
(
GET $WICKED_CREW_URL/api/v1/mcp/servers— the daemon this run belongs to, never a typed port; or studio MCP tools) and pick a key no other server holds: install refuses a key held by a different server. Record whether an OpenAPI document was given and whether to install when complete (the operator still decides at the install gate). - source-discovery — with an OpenAPI document, run the
openapiaction (step 2) and report the tool count, the classes and everyskippedoperation; without one, inventory the integration surface (endpoints, SDK calls) the tools will wrap. - design — the tool table (name, schema, annotations, class), the auth plan (scheme and
the one
<SERVER>_TOKEN, every non-secret parameter inmcp-server.config.json) and the observability plan, each checked against the MCPS rules below. - build — scaffold (step 1), then branch A (generated tools from
tools.json) or branch B (hand-written tools throughdefineTool), with a contract test per tool andnpm testgreen; probe it (step 4). - install-plan / install — a Tool phase runs
install.py --from-run --dry-run --json(the plan), then the operator's consent gate offers its choices with their files, then a Tool phase runsinstall.py --from-run --target <the approved choice>(step 5). Read its record:smoke(okorpending_credential),registered(true,"updated", orfalsewithmissing/remedyorreason) andclis(per-CLI results, or why they were skipped). Exit 0 means staged; a disclosed pending credential is not a failure.
Steering this server follows
The pack governance/packs/mcp-server in wicked-core is the source of truth; when an estate
store is present, recall the rules with rules.recall {scope: "wiki:governance",
steering_type: ...} instead of re-deciding them. The TypeScript template satisfies each:
- MCPS-1001 — TypeScript on Node >= 22 with fastmcp.
- MCPS-1002 — OpenTelemetry spans and metrics via
@opentelemetry/sdk-node; exporters only byOTEL_*env. - MCPS-1003 — loglayer with the OpenTelemetry plugin, a request-scoped child logger, stderr never stdout.
- MCPS-1004 — authentication on every tool and resource; one secret variable from env;
non-secret parameters in
mcp-server.config.json. - MCPS-1005 — input validated before the handler, egress pinned to the base URL, allowlisted arguments, a rate limit.
- MCPS-1006 — a contract test per tool plus the stdio conformance smoke under
npm test. - MCPS-1007 — SPDX headers; no telemetry leaves the process without an operator-set endpoint.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

