ThirdBrain skills-mcp

Library-agnostic MCP server that serves one or many directories of Agent Skills (SKILL.md folders, flat or nested) over the Model Context Protocol, each library under its own namespace. Part of the ThirdBrain Business Operating Brain (BOB) tooling. Built for the ThirdBrain BOB library (~400 skills) and verified against the GBL library (~400 skills). Includes a pull client that syncs skills from any SEP-2640 server to disk with digest verification.

It implements the MCP Skills extension (SEP-2640) for hosts that understand skill:// resources, and a small set of discovery tools for hosts that do not yet, so skills are loaded on demand instead of being copied into every agent's skills folder.

What it exposes

The agent flow is progressive disclosure: search → get_skill → read_skill_file. Only the skill you pick enters context.

Related MCP server: Taproom

Playbooks and value chains

A ThirdBrain vault keeps two more things next to its skills: playbooks (multi-step workflows that chain skills into an outcome: trigger → numbered AGENT/HUMAN steps → outcome; only the vault-shipped ones under 00-CORE/Playbooks/ are served) and value chains (end-to-end business journeys such as lead-to-cash with ordered stages, to which skills and playbooks are mapped). The server serves both when the information is present, and nothing otherwise: the tools, prompt and resource templates only appear when at least one library serves them, and hosts are told through tools/list_changed after the first scan.

The root is the boundary. The server reads only what is inside the directory, zip or URL you give it, never folders above or beside it. So --lib bob=<vault>/00-CORE/Agents/skills serves skills only, as before; to serve playbooks and value chains, give the vault root (or a release zip of it). The layout is recognised from what is inside the root, so the same pack works as a checked-out folder, a local zip, or a GitHub release asset:

--vault NS=DIR or "vault" in the config file names a vault directory explicitly, the one case where content outside the root is served, by your choice; "vault": false turns the extras off for one library. Inside the vault root only these locations are read:

Paths never leave the server: vaultPath in playbook output is relative to the vault root, and archive extraction directories are not shown.

How steps are read. Steps are the numbered items of the ## Steps section, in the playbook-runner grammar: N (countdown). head → action (AGENT|HUMAN[ — note]), where the head is skill, skill (route), [[Playbook]] or script:file.py, and bold or code decoration around it is ignored. An item runs over its indented continuation lines up to the next item or heading (numbered lines inside code fences or indented deeper are not items). The actor is the parenthesis ending the item's first paragraph ((AGENT), (HUMAN + AGENT), (HUMAN, 5 min), (HUMAN decides, AGENT drafts)), else the first one inside it, else the one ending a later paragraph. A step's skill is the head when it names a skill, else the first served skill the step links to — [[skill]], [[skill/SKILL.md|…]], {skills.root}/skill/… or skill/scripts/…; links to other notes (playbooks) are not skills, and embeds (![[…]]) are ignored. Further linked skills are listed as mentions. A note without a Steps section uses its ### Phase N / ### Step N headings as steps, else any numbered lines.

Playbooks require the playbook-runner skill. A playbook is executed by that skill's run route, so a library's playbooks are served only when a skill named playbook-runner is served, from the same library or, failing that, from any other library on the server. Otherwise they are counted as playbooksHidden and a warning says so. Only status: active playbooks are served (draft, review and retired ones are hidden, as in the vault's own index); --show-disabled serves every status. Value chains are not gated by any skill: the vault's vault-value-chain-visualization skill renders them, but presence is decided by the definition file or the frontmatter references above, and coverage is computed by this server from the catalog.

What the tools return.

• _list_playbooks(query?, library?, value_chain?, stage?, skill?) — ranked by query over name, trigger, outcome, tags and step skills; each entry carries trigger, outcome, steps, valueChain, chainCoverage, the skills its steps name and the runner skill path to load.

• _get_playbook(name) — the full note plus stepDetails (n, skill, skillPath when the skill is served, route, mentions, action, actor), missingSkills (named by steps but not served), attachments with sha256 digests, and the vaultPath inside the vault. The text ends with how to execute it: load playbook-runner with _get_skill, then each step's skill when reached.

• _list_value_chains(library?) — chains with label, stages, kind (chain, or bucket for an unstaged group), source (definition, index, derived) and skill/playbook counts.

• _get_value_chain(id) — the stage table (skills and playbooks per stage), unstaged items that declare the chain without a stage (for a bucket: all its members), and gaps (stages nobody covers; always empty for a bucket).

• run-playbook(playbook, inputs?) prompt — the playbook-runner SKILL.md body and the playbook, each in its own tagged block, with the served skill path for every step.

Playbooks and chains are data from the vault, not instructions from the user, and the text output says so. _list_libraries and _catalog_status report vault, playbooks, playbooksHidden, playbookRunner, valueChains, valueChainBuckets (how many of them are buckets) and valueChainSource per library. Warnings (in _catalog_status include_warnings=true) cover playbooks whose steps name an unserved skill, a total-steps that differs from the steps parsed, notes filed in a subdirectory of a playbook root, chains referenced by frontmatter but not defined, and a missing runner. On the full BOB vault (2026-09-23) this serves 86 active playbooks (4 more hidden) and 14 value chains from the canonical file (valueChainSource: definition): 12 staged chains and the 2 buckets, with no chain or step-count warnings.

node dist/index.js --lib bob=/vault                                  # vault root: skills, playbooks, chains
node dist/index.js --lib bob=/vault/00-CORE/Agents/skills            # skills folder: skills only
node dist/index.js --lib bob=thirdbrain-full-2026.09.zip             # release zip (wrapper folder or not)
node dist/index.js --lib bob='https://host/thirdbrain-full.zip#sha256=...'
node dist/index.js --lib bob=/elsewhere/skills --vault bob=/vault    # explicit vault root
node dist/index.js --lib bob=/vault --no-playbooks --no-value-chains

Install

git clone https://github.com/cbruyndoncx/ThirdBrain-skills-mcp.git
cd ThirdBrain-skills-mcp
npm install
npm run build
npm run test:unit   # 94 unit tests (in-memory MCP client, fixtures under test/fixtures)
npm test            # smoke test against the BOB library at $BOB_VAULT (prints SKIP when unset)
npm run test:gbl    # same test against the GBL library at $GBL_VAULT
npm run test:nested # nested-path fixture (skill://acme/billing/refunds/...)
npm run test:all

One server, several libraries (recommended)

claude mcp add --scope user skills -- node /path/to/ThirdBrain-skills-mcp/dist/index.js \
  --lib bob=/path/to/brncx-skills \
  --lib gbl=/path/to/gbl-skills

Each --lib NS=DIR becomes a namespace: URIs are skill://bob/ab-test-setup/SKILL.md, tools accept a bare name when it is unique across libraries, or bob/period-in-review when the same name exists in several. skills_list_libraries shows what is served; library=bob scopes search and listing. The project .mcp.json uses this form with one library: node ${PWD}/dist/index.js --lib bob=${BOB_VAULT:-/mnt/c/users/bruyn/documents/brncx-skills}, so it works when the MCP client is started in the repository folder after npm run build; set BOB_VAULT to point it at another vault.

One library, un-namespaced

node dist/index.js --root /path/to/skills --name bob     # URIs: skill://<skill>/..., tools bob_*

--name sets the MCP server name and the tool prefix. Running several single-library instances side by side also works (different --name per instance).

Streamable HTTP instead of stdio:

node dist/index.js --lib bob=DIR --http 3939   # endpoint: http://127.0.0.1:3939/mcp (stateless)

Pull skills from any SEP-2640 server

node dist/index.js pull --url http://127.0.0.1:3939/mcp --list
node dist/index.js pull --url http://127.0.0.1:3939/mcp ab-test-setup gbl/period-in-review --to ./skills
node dist/index.js pull --all --keep-path --to ./skills --command node dist/index.js --lib bob=DIR
node dist/index.js pull --with-deps --keep-path --sync --to ~/.cache/skills-mcp-client/bob bob/bob-marker-sweep \
  --command node dist/index.js --lib bob=/path/to/brncx-skills

pull walks skills/list, reads every file with resources/read, verifies each sha256 digest against the manifest, refuses paths outside the skill, and writes atomically. --keep-path keeps the namespace as a folder; --force overwrites; --dry-run verifies without writing. --sync updates an existing folder in place: files whose sha256 already matches are kept without a network read, changed or missing ones are fetched, and files no longer in the skill are deleted, so a re-run on an unchanged skill costs one skills/list and some local hashing. Without the CLI installed, npx github:cbruyndoncx/ThirdBrain-skills-mcp pull ... builds and runs it.

--with-deps also pulls every skill a selected skill declares as a required runtime dependency (the _meta["io.modelcontextprotocol.skills/dependencies"].required list, see Runtime dependencies), transitively and from the same library, and writes each next to it (<to>/<ns>/<dep>/ with --keep-path), which is where a script importing a sibling skill looks for it. Each added skill is logged (deps bob/bob-marker-sweep → bob/context-pack). Optional dependencies are not pulled. A required dependency the server does not serve in the same library stops the pull with an error rather than leaving a closure that cannot run; pull without --with-deps to fetch the skill alone. The flag is off by default, so existing invocations behave as before. On the BOB vault, pull --with-deps --keep-path bob/bob-marker-sweep writes bob-marker-sweep and context-pack (measured 2026-09-23).

Configuration

BOB_SKILLS_* environment variables are still accepted as aliases.

Breaking change (after 1.3.0): the root variable is SKILLS_MCP_ROOT; SKILLS_ROOT is no longer read. Skill libraries use SKILLS_ROOT as their own contract (the folder their scripts resolve {skills.root} from), so a host exporting it for the skills and passing its environment to this server gave the server a second, un-namespaced library: next to --lib it refused to start (--root cannot be combined with other libraries), alone it silently served that folder.

Nested libraries: a skill's URI path is its directory path below root, prefixed by the namespace when there is one (skill://acme/billing/refunds/SKILL.md, skill://bob/ab-test-setup/SKILL.md). Tools accept the bare name (when unique across all libraries), <namespace>/<name>, or the full path.

Always ignored inside skills, silently: tool and build folders (.venv, venv, node_modules, __pycache__, site-packages, .git, .pytest_cache, .mypy_cache, .ruff_cache, *.dist-info, *.egg-info), compiled artefacts (.pyc, .pyo, .so, .dylib, .dll, .whl) and type stubs (.pyi). Also not served, but reported as one catalog_status warning per skill (<skill>: N file(s) skipped (… over SKILLS_MAX_FILE_BYTES: …; … symlink: …; … dotfile: …), up to three names each): files over SKILLS_MAX_FILE_BYTES, symlinks, and dotfiles or dot-folders. The BOB vault has none (measured 2026-09-23).

Archive libraries

A library root may be a .zip instead of a directory:

skills-mcp --lib bob=/srv/libraries/bob-skills.zip
skills-mcp --root ./my-skills.zip

The archive is a transport container, not served content. On the first scan it is extracted into SKILLS_CACHE_DIR/<sha256-of-zip>/, and discovery, linting, digests and URIs then run over ordinary files — nothing downstream knows an archive was involved. Because the cache is keyed by content digest, a rescan of an unchanged archive costs a single stat; replacing the archive extracts the new one and prunes the extraction it replaced.

Skills inside the archive are laid out exactly as in a directory library, so a wrapper directory (as produced by git archive or GitHub's "Download ZIP") is fine — discovery descends into it.

Archives may not appear inside a library. A bundled payload.zip would be served as an opaque base64 blob that the risk linter cannot read, so any skill containing one is refused and reported:

sneaky: bundles archive file(s) (notes.tgz, payload.zip); skills may not contain archives, skill not served

This applies to directory libraries too, and covers .zip .tar .tgz .tar.gz .gz .bz2 .xz .7z .rar .jar .war .apk .iso .dmg .cab — renaming a zip to .tgz does not get past it. The count appears in --stats as archiveSkillsRejected. One bad skill is withheld; the rest of the library still serves.

Remote (URL) libraries

A library may also be an https URL of a .zip, so a published release can be served without checking anything out:

# pinned to a digest (recommended)
skills-mcp --lib sales='https://host/pack-sales-free-v2.7.0.zip#sha256=fac65d24...'

# or in the config file
{"libraries": [{"namespace": "sales", "url": "https://host/pack.zip", "sha256": "fac65d24..."}]}

GitHub release assets work directly, including private ones — export GH_TOKEN and use the asset API URL:

export GH_TOKEN=$(gh auth token)
skills-mcp --lib sales="https://api.github.com/repos/OWNER/REPO/releases/assets/<id>#sha256=<hex>"

Integrity. The archive is verified before extraction: against the sha256 pinned in config, or failing that a <url>.sha256 sidecar next to the asset. A mismatch is refused outright rather than served. Pinning is stronger than the sidecar, since the sidecar travels the same wire as the zip.

Caching. Downloads are keyed by content digest, the same key the extractor uses. A pinned URL that has already been fetched never touches the network again — the second start of the server above scans in ~80 ms. A remote library is fetched once per process; change the URL or the pin to pick up a new version.

Failure handling. If a refresh fails but a previous extraction is still cached, the cached copy keeps being served and a warning is recorded — a transient DNS blip during a background rescan will not empty a live library.

What is refused:

Query strings and fragments are stripped from anything logged, so credentials in a signed URL do not reach a log line.

What is rejected in an archive

The archive is treated as untrusted input. Extraction refuses, before writing anything to disk:

The byte budget is enforced while inflating, not from the sizes declared in the central directory, since those are attacker-controlled and may lie. A failed extraction leaves no partial tree behind, and extracted files are always written non-executable (0644).

Runtime config file and hardening

node dist/index.js --config skills.json          # re-read on every rescan (default 60 s) and on SIGHUP

{ "libraries": [
    { "namespace": "bob", "root": "/path/to/brncx-skills/00-CORE/Agents/skills",
      "title": "BOB – Business Operating Brain", "source": "brncx-skills", "version": "2026.09",
      "metadata": { "channel": "stable" } },
    { "namespace": "gbl", "root": "../gbl-skills/00-CORE/Agents/skills", "noScripts": true, "vault": false },
    { "namespace": "acme", "root": "../acme/skills", "vault": "../acme" } ],
  "noScripts": false, "lint": true, "playbooks": true, "valueChains": true, "excludeTiers": [] }

vault is optional: a path (relative to the file) naming a vault directory explicitly when the library root is only the skills folder, or false to serve that library's skills only. playbooks and valueChains are global switches (default true); excludeTiers (an array or a comma string, default none) is the --exclude-tiers list.

Libraries from the file can be added, removed or re-pointed while the server runs; libraries given on the command line stay fixed. Relative roots resolve against the file's directory. A broken edit is logged and the previous set is kept. Changes trigger resources, tools and prompts list_changed notifications. kill -HUP <pid> forces an immediate reload.

Library paths never leave the server. list_libraries, catalog_status, the initialize instructions and skill output show what is loaded, not where it is: the optional title, source (the vault, repository or team the library comes from), version and free-form string metadata from the config file, the kind (directory, archive, url), and for archive and url libraries the sha256 of the archive currently extracted. Warnings returned by catalog_status have root paths replaced by <namespace>. Roots still appear in the server log and in --stats, which are for the operator. Metadata fields are only available in the config file; a library given as --lib NS=DIR shows its namespace and kind.

The server never executes anything. Three additional layers label or withhold risky content:

The linter labels, it does not block. On the BOB vault (--lib bob=<vault> --stats, measured 2026-09-23: 390 skills served, 8 hidden) it flags 15 served skills (flaggedSkills): 11 curl … | sh install instructions for third-party tools, 2 skills whose text documents prompt-injection phrasing, 1 whose test fixture holds a sensitive path, and 1 env-exfil match. A 16th, hidden skill is flagged for test fixtures with sensitive paths and credential-shaped strings. Those are legitimate but worth knowing before a host runs them. Rules live in src/lint.ts.

Bundled scripts

Skills may ship scripts (scripts/extract.py), and this server serves them like any other file. What happens on the receiving side is up to the host; SEP-2640 sets the rules:

• Fetched on demand, verified, cached. Hosts SHOULD cache skill files locally as they are read, not in bulk, and MUST verify each file against its sha256 digest from skills/list / skills/get. The cache must be writable only by the host (or re-hashed on every use), live outside every local skill-discovery path, and be separated per server.

• Cached is not local. A cached script keeps its MCP origin, even after a restart or after the server is disconnected. It never gains the trust of a filesystem skill.

• No execution without approval. Hosts MUST NOT run a script from an MCP-served skill, or any command its instructions direct the model to run, without explicit per-skill user approval. That approval is bound to the skill's file set and digests; any change revokes it.

• No executable bits. Files travel one by one as resources, without mode bits or symlinks, so a script is run through its interpreter (uv run scripts/extract.py, python scripts/extract.py), never as ./extract.py.

Hosts without SEP-2640 support reach skills through the tools, so this server repeats those rules to the model. The server instructions, get_skill and the use-skill prompt label every skill with its source server (Source: <name> (MCP-served skill, not installed locally)). Every file in get_skill carries its digest; every script also carries its interpreter (uv run for a Python file with a PEP 723 # /// script header, else python, bash, node, ... by extension) and, for Python, pep723: true|false, in the structured output and in the text file list (run with: uv run (PEP 723)). read_skill_file returns the same two fields for a script. When a skill or its dependency closure bundles scripts, the text output also lists the digests and tells the model to run scripts only from a verified local copy of the skill and the skills it depends on, because scripts import or read their sibling files and those skills:

1. Copy the skill and its dependency closure into a cache folder that no host scans for skills, preferably with skills-mcp pull --sync --keep-path --with-deps --to ~/.cache/skills-mcp-client/<server> <skill-path> (--url or --command as the client is configured). No file content passes through the conversation, digests are verified, and re-running it each session is cheap thanks to --sync. Only when the CLI cannot run: read_skill_file per needed file of the skill and of each skill in its closure (the guidance names them), written byte-for-byte at its relative path and checked against the digests, never retyped.

2. Show the user what will run and get their approval. The approval covers the skill and its dependency closure, whose code runs too, and the guidance lists the closure (bob/bob-marker-sweep, bob/context-pack). A declared dependency the server does not serve is named with a warning.

3. Run each script with the full command the guidance renders, from the cached skill folder:

   cd ~/.cache/skills-mcp-client/bob/bob/bob-marker-sweep && SKILLS_ROOT=~/.cache/skills-mcp-client/bob/bob VAULT_PATH=<workspace> uv run scripts/bob_marker_sweep.py … --vault <workspace>

   • The interpreter is per file: uv run when the script has a PEP 723 header (it installs the inline dependencies; plain python does not), otherwise the one for its extension.

   • SKILLS_ROOT is always set, to the cached library (<cache>/<ns>), so a command written as {skills.root}/<other>/scripts/x.py runs the verified cache copy rather than a local install. It is library-agnostic; this server itself no longer reads SKILLS_ROOT (see Configuration).

   • VAULT_PATH=<workspace> is added when the library is vault-shaped (a vault was detected) or the skill's text or scripts mention VAULT_PATH / --vault; --vault <workspace> is appended to a script whose source takes a --vault option. <workspace> is the user's vault or workspace, never the cache folder, which a script would otherwise take as its workspace.

   • Up to 8 commands are rendered (the script named after the skill first, test files left out); the rest follow the same form. … stands for the script's own arguments.

   Following the rendered guidance for bob-marker-sweep against a temporary workspace (… --dry-run --vault <tmp-ws>) exits 0 from the cache (verified 2026-09-23).

read_skill_file attaches a short version of these steps, with the digest and the interpreter, to every executable file. Skill output (get_skill, read_skill_file, use-skill) only shows paths relative to the skill folder, never where the skill lives on the server's disk.

Runtime dependencies

A skill that runs another skill's code declares it in its SKILL.md body with the vault's marker line, which the server parses at scan time:

- [[context-pack/SKILL.md|context-pack]] — **runtime dependency.** Filed tasks use the pack's output.tasks.
- [[skillsmith/SKILL.md]] — **optional runtime dependency.** Used when present.

The link may carry an alias or not. Required dependencies form the closure: transitive, cycles followed once, the skill itself excluded. Optional ones are reported but never pulled. They are exposed as _meta["io.modelcontextprotocol.skills/dependencies"] = {required, optional} in skills/list, skills/get and resources/list, and in get_skill as dependencies, dependencyClosure (skill paths) and missingDependencies (required but not served), plus a Runtime dependencies: line in its text. A required dependency that the library does not serve is also a catalog_status warning. On the BOB vault 142 skills declare at least one required dependency (measured 2026-09-23).

Dependencies resolve inside the skill's own library only; cross-library dependencies are not supported. A bob skill depending on context-pack is satisfied by bob/context-pack, never by a context-pack in another namespace.

requires is not a dependency list. Frontmatter requires names external setup (tools, API keys). It is still published as _meta["io.modelcontextprotocol.skills/requires"] for compatibility, and get_skill returns it as setup with a Setup (… not skills): text line.

For skill authors this means:

• Reference scripts by path relative to the skill root, and show the interpreter in the command: uv run scripts/extract.py input.pdf (or python scripts/extract.py), not ./scripts/extract.py or an absolute path.

• Do not rely on a script's executable bit, on symlinks, or on files outside the skill directory other than declared runtime dependencies, reached through {skills.root}/<other>/ or as a sibling folder.

• Declare Python dependencies inline with a PEP 723 # /// script header, which uv run installs; a requirements.txt in the skill is optional. .venv and node_modules are never served.

• Declare every skill whose code yours runs with the runtime-dependency marker line above.

• Expect a host to ask the user before running anything, and write instructions that still make sense if the user says no.

pull into a cache folder, as above, keeps skills out of the host's reach as local skills. Pulled with --to into a folder the host scans for skills, they become local skills instead: an explicit install, not a cache. Pull only from servers you trust, or use --no-scripts on the serving side to withhold scripts entirely.

Spec conformance notes

• URIs are skill://<skill-path>/<relative-path>; the last skill-path segment equals frontmatter name. A warning is recorded when a directory name and its frontmatter name differ.

• Digests are computed lazily and cached per file mtime, so skills/list is cheap after the first call.

• SEP-2640 limits (512 files, 16 MiB per skill) are enforced/flagged: file lists are truncated at 512 and oversized skills are listed in <prefix>_catalog_status include_warnings=true. No BOB skill exceeds either limit (measured 2026-09-23: largest nl-accounts-review at 3.8 MiB, most files 166).

• skills/get answers for hidden (disabled) skills too, as the spec requires.

Layout

src/config.ts       env/CLI configuration
src/frontmatter.ts  SKILL.md frontmatter parsing
src/catalog.ts      directory scan, file inventory, digests, change detection
src/archive.ts      zip-backed libraries: strict extraction, path/bomb/symlink defences, digest cache
src/remote.ts       remote libraries: https fetch, redirect/credential rules, digest verification
src/search.ts       ranked keyword search over name/description/tags/body
src/vault.ts        vault extras: playbook discovery/step parsing, value-chain definitions and coverage
src/server.ts       MCP wiring: extension methods, resources, tools, prompts
src/lint.ts         scan-time risk linter (labels, never blocks)
src/pull.ts         client: sync skills from a SEP-2640 server with digest verification
src/index.ts        entrypoint: `serve` (default; stdio or --http) and `pull`
test/unit/*.test.ts unit tests (config, frontmatter, catalog, search, server via InMemoryTransport, pull, hardening, archive, remote, vault, deps, tiers)
test/smoke.ts       end-to-end test via a real MCP client (parametrised by root/name)
test/nested.mjs     nested-path + duplicate-name test against test/fixtures/nested