Skip to main content
Glama

toolshed-mcp

One MCP server that gives any coding agent the tools this machine already has: every skill, agent and slash command in every corpus on disk, plus a proxy onto external MCP servers, plus GitHub as a runtime source.

It stands alone. It does not import, link against, spawn or proxy through skills-library, orchestrator or verifier — with one deliberate exception, the install path, described below.


Install

git clone https://github.com/ashikonik/toolshed-mcp.git
cd toolshed-mcp
npm install
npm run build
bash scripts/install.sh --list     # print the resolved command per harness, write nothing
bash scripts/install.sh --apply    # register into every harness found

--apply is idempotent: it refuses to replace an existing registration of the same name. --force replaces it. --project <dir> writes project-scoped config for the harnesses that support it.

The server is always launched as node <abs path>/dist/index.js — never npx -y, never bunx. It must start offline, from a known version.

Harness matrix

Harness

Config

Format

claude-code

~/.claude.json

JSON, mcpServers

puku-cli

~/.puku-cli/puku-cli.json

JSON, mcpServers

opencode

~/.config/opencode/opencode.json

JSON, mcp key, type:"local", command as an array

codex

~/.codex/config.toml

TOML, [mcp_servers.toolshed]

Each harness keeps its registrations in its own file with its own schema, so the installer detects the schema per harness rather than assuming one. A .bak is written before the first change to any file.


Related MCP server: getagentictools MCP server

The tools

Tool

What it does

search_registry

Ranked BM25 search across every corpus, filtered by source or kind

get_entry

One skill, agent or command: frontmatter, body, provenance

get_entry_bundle

The entry plus its supporting files

list_sources

Every corpus, its root and how many entries it contributed

list_mcp_servers

MCP servers on this machine, installed vs configured-only

list_agent_types

Per-harness agent types actually available, and any missing built-ins

add_github_source

Register owner/repo as a source: fetch, index, make searchable

install_skill_from_github

Fetch one skill from owner/repo/path and install it into a harness

proxy_call

Invoke a tool on a connected external MCP server, as server__tool

proxy_discover

List the tools of a connected external server

Every write tool takes apply and defaults to a dry run. Every tool declares all four MCP annotations, and every handler returns an error result rather than throwing.


Deduplication, and why provenance matters

Several corpora on a typical machine overlap heavily — the same skill copied into two trees. The registry collapses an entry only when both its name and its content hash match, so a genuine content revision under the same name survives as a second entry.

A byte-identical copy is collapsed, but the corpus it came from is not lost: it is recorded on the surviving entry as an alias, and surfaces as also-in: in get_entry and as aliases in search_registry hits. list_sources reports what each corpus contributed, so a corpus whose skills all exist verbatim elsewhere still shows a non-zero count instead of reading as empty.

$ toolshed-mcp → get_entry skill:sna:api-design
# api-design
kind: skill
source: sna
also-in: ecc-agent-skill
id: skill:sna:api-design

The delegation contract with skills-library

For a skill fetched from GitHub, the toolshed fetches and indexes; it never writes into a harness directory itself. The install is delegated over MCP to skills-library, which owns the path whitelist, the tier policy and the dry-run rule — and which applies its own gates. The toolshed's own registry handles local-corpus reads; only the GitHub install path crosses the seam.

Two details make that seam work:

  • skills-library resolves ids against its own index, so a GitHub skill must be staged into a corpus it can see before it can be installed. The toolshed writes the staged corpus and points SKILLS_LIBRARY_ROOT at it.

  • skills-library reads further top-level fields out of the index at startup (packs, domains, …) and throws on the first one that is missing. The toolshed therefore merges into the existing index document rather than replacing it, changing only the skills array and keeping counts in step.

A delegated install looks like this — note the policy refusal, which is skills-library's, not the toolshed's:

$ toolshed-mcp → install_skill_from_github {repo, path, harness, apply:true}
Installed 'docx' into claude-code via skills-library.
{ "gated": true, "rule": "SL-3", "reason": "Overwriting replaces something that is already there…" }

The Explore bug, and what a registry can and cannot do

Error: Agent type 'Explore' not found. Available agents: general-purpose is a bug in puku-cli's shipped bundle, not in any MCP server. The bundle contains

function mCe(){return!1}

which gates Explore and Plan out of the built-in agent list. general-purpose is added unconditionally, which is why only it appears in the error message. The agent-type registry lives in the CLI's own process, so an MCP server cannot extend it — no MCP server, including this one, can restore those two built-ins.

What this server does do is make the gap visible:

  • list_agent_types reports, per harness, which agent types are actually available, and names the missing built-ins:

$ toolshed-mcp → list_agent_types
puku-cli: general-purpose, code-reviewer  MISSING BUILT-IN: Explore, Plan
claude-code: general-purpose
opencode: general-purpose
codex: general-purpose, a11y-architect, agent-evaluator, …
  • scripts/install.sh prints the same note when it finishes.

The portable half, which is the one that matters

The genuinely useful half is an agent file any harness can load, and that does not depend on the bundle. puku-cli reads personal agents from ~/.puku-cli/agents/*.md, so skills-library's install_agents was extended to support puku-cli:

$ skills-library → install_agents {harness:"puku-cli", ids:["agent:code-reviewer"], apply:true}
{ "status": "written", "path": "~/.puku-cli/agents/code-reviewer.md" }

$ puku-cli agents
2 active agents

User agents:
  code-reviewer · inherit

Built-in agents:
  general-purpose · inherit

That change lives in the authoring package, not in the published copy of the skills-library, because the published tree is regenerated from it and a hand edit there would be wiped on the next rebuild.

The one-line patch, if you want the built-ins back

For the built-ins themselves, the patch is a single byte in the installed bundle:

# at ~/.npm-global/lib/node_modules/@puku/puku-cli/dist/cli.mjs
#   function mCe(){return!1}   →   function mCe(){return!0}

This is documented, not applied. Two reasons not to apply it silently: it is a vendor file, and npm update -g @puku/puku-cli will revert it. Apply it deliberately if you want it, and re-apply after upgrades.


GitHub as a runtime source

add_github_source fetches a repository, indexes its SKILL.md files and makes them searchable like any local corpus.

How the fetch works

The fetch is a blobless partial clone with a sparse checkout restricted to the conventional skill paths. The server is asked for tree objects only, and the blobs for the paths that matter are fetched on demand.

This matters because a GitHub archive is unbounded. The expo/exact archive is 212 MB and holds eight skill files. The sparse clone of the same repository is 39 KB of skill files and about 3 MB on disk:

Repository

Archive route

Sparse clone route

expo/exact

212 MB, 8 entries

3 MB, 8 entries

anthropics/skills

12 MB, 20 entries

1 MB, 20 entries

A registry that indexes skills has no use for a repository's assets, source code or history, so it does not download them.

The archive route from codeload remains as a fallback, for repositories where git is unavailable or the sparse clone finds nothing.

Safety properties, all of them tested

  • Dry run by default. apply: true is required to write anything.

  • A token is never echoed. GITHUB_TOKEN is read from the environment and redacted from every error message before it can reach a log or a tool result.

  • Path-traversal guards on every archive entry. An entry whose resolved path would escape the destination is refused, and one bad entry does not kill the whole archive.

  • A skill path is validated before anything is fetched or written: no absolute paths, no .., no separators.

  • A download cap. The archive route refuses to exceed TOOLSHED_MAX_DOWNLOAD_BYTES (50 MB by default) and says what to change. The sparse route is bounded by the sparse checkout itself.

install_skill_from_github fetches one skill and hands the install to skills-library, as described above. The requested path is added to the sparse checkout patterns, so a skill in an unusual location is still found.


The proxy

The proxy is what makes this a shed rather than a viewer. It connects to external MCP servers you list in ~/.toolshed/proxies.json and exposes their tools under a server__ namespace.

{
  "targets": [
    {
      "name": "library",
      "command": "node",
      "args": ["/path/to/skills-library-mcp/dist/index.js"],
      "timeoutMs": 15000
    }
  ]
}
$ toolshed-mcp → proxy_discover {server:"library"}
library__search_library  Rank skills and agents by relevance to a query…
library__get_skill       Returns one skill: its SKILL.md body…

$ toolshed-mcp → proxy_call {server:"library", tool:"library__search_library", arguments:{…}}

A server that hangs is timed out and killed, process group and all, so it cannot outlive the call or linger as an orphan. The timeout is per target.

The proxy does not reach the already-connected local servers: the toolshed is independent of them by design.


Configuration

Paths are runtime configuration, never build artefacts, so the published package carries no absolute path to any machine.

Variable

Meaning

TOOLSHED_SNA_ROOT

Root of the skills-and-agents corpus

TOOLSHED_ECC_ROOT

Root of the ECC corpus

TOOLSHED_EXACT_ROOT

Root of the expo/exact corpus

TOOLSHED_SOURCES

JSON array of extra source definitions

TOOLSHED_HOME

Where the cache and the source registry live (default ~/.toolshed)

TOOLSHED_CACHE_ROOT

Where fetched repositories are cached

TOOLSHED_PROXY_CONFIG

Where the proxy target list lives (default ~/.toolshed/proxies.json)

TOOLSHED_FETCH_TIMEOUT_MS

How long a repository fetch may take (default 600000)

TOOLSHED_MAX_DOWNLOAD_BYTES

The largest archive the fallback route will download (default 52428800)

TOOLSHED_SOURCES takes a JSON array of source definitions:

[
  { "id": "mine", "label": "My skills", "root": "/path/to/skills", "origin": "local", "layout": "skill-dirs" }
]

Layouts: skill-dirs, skill-files, agent-files, command-files, agent-skill-dirs, github-tree.


Live reload

The registry is derived from files on disk, so it must not go stale. Each source is fingerprinted (mtimeMs + size + file count) on every call, and the registry is rebuilt when a fingerprint changes. A corpus that fails to load keeps serving its last known entries, and the error is surfaced in the "not found" message so the caller knows the entry may exist on disk.

The skills-and-agents corpus is read through its index.json artefact, which is a build output. If that index is stale, so is the registry's view of that corpus — rebuild the library and the toolshed picks the change up on the next call, with no restart.


Development

npm run build
bash scripts/run-tests.sh

The test suite runs in-process over the MCP SDK's InMemoryTransport. The wrapper fails when zero tests ran, because a green run that ran nothing is worse than a red one.

Layout:

src/
  index.ts         # the only file that knows stdio
  server.ts        # the tool surface
  registry.ts      # the union index, dedupe, BM25 search
  sources.ts       # per-corpus discovery and parsing
  frontmatter.ts   # tolerant YAML reader, key normalisation
  mcp-servers.ts   # local MCP servers, installed vs configured-only
  agent-types.ts   # per-harness agent-type probe
  github.ts        # fetch, cache and index a GitHub source
  proxy.ts         # stdio client for external MCP servers
  delegate.ts      # the skills-library delegation seam
  results.ts       # asText / asError helpers
  types.ts
  tests/

stdout carries protocol traffic only; diagnostics go to stderr with a [toolshed] prefix.


Licence

MIT. See LICENSE.

Available Tools

10 tools
add_github_sourceRegister a GitHub repository as a sourceA
Idempotent

Fetch a GitHub repository, index its skills and agents, and register it as a registry source so its entries become searchable. Not covered by install_skill_from_github, which installs a single skill into a harness.

Inputs: repo (required), ref, apply, label, +1 more.

get_entryRead one entryA
Read-onlyIdempotent

Read one skill, agent or command by id or name, including its frontmatter and body. The id is skill:<source>:<name>, and the shorter skill:<name> and a bare name also resolve. Not covered by get_entry_bundle, which also returns supporting files.

Inputs: id (required), source.

get_entry_bundleRead an entry and its supporting filesA
Read-onlyIdempotent

Read one entry together with the files that belong to it, such as reference documents or scripts. Not covered by get_entry, which returns only the entry itself.

Inputs: id (required), max_files.

install_skill_from_githubInstall a skill from GitHubA
Idempotent

Fetch one skill from a GitHub repository and install it into a coding harness, with the install performed by the skills-library server so its path and tier policy applies. Not covered by add_github_source, which registers a whole repository as a source.

Inputs: path (required), repo (required), harness (required), ref, +3 more.

list_agent_typesList available agent typesA
Read-onlyIdempotent

Report which agent types each harness on this machine can actually spawn, and name any built-in types that are missing. Not covered by list_mcp_servers, which lists server registrations rather than agent types.

Inputs: harness.

list_mcp_serversList MCP serversA
Read-onlyIdempotent

List MCP servers registered in the harness configs on this machine, distinguishing those whose executable is present from those that are configured only. Not covered by list_sources, which lists corpora of skills and agents.

Inputs: installed_only.

list_sourcesList registry sourcesA
Read-onlyIdempotent

List every corpus registered on this machine with its kind, root and entry count. Counts are read at the time of the call. Not covered by list_mcp_servers, which lists MCP servers rather than corpora.

Inputs: no named parameters.

proxy_callCall a tool on a proxied MCP serverA

Invoke a tool on an external MCP server that this server proxies, addressed as server__tool. Not covered by proxy_discover, which lists the tools without calling them.

Inputs: tool (required), arguments.

proxy_discoverList the tools of a proxied MCP serverA
Read-onlyIdempotent

List the tools exposed by an external MCP server that this server proxies, or list the proxied servers themselves when no server is named. Not covered by proxy_call, which invokes a tool rather than listing them.

Inputs: server.

search_registrySearch the registryA
Read-onlyIdempotent

Search skills, agents and commands across every corpus registered on this machine. Returns ranked hits with the source each came from. Not covered by search_library, which searches one corpus only.

Inputs: query (required), kinds, limit, sources.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.2/5.0

    Scored across 10 tools

    Disambiguation5/5

    Each tool targets a distinct action and resource, and the descriptions explicitly contrast overlapping neighbors such as get_entry vs get_entry_bundle, list_sources vs list_mcp_servers, and proxy_call vs proxy_discover. The install_skill_from_github vs add_github_source distinction is also clearly drawn.

    Naming Consistency4/5

    All names use snake_case and are readable, but the pattern is not uniformly verb_noun: proxy_call and proxy_discover use a proxy_ prefix while others start with verbs like get, list, search, add, and install. Minor deviation only, not confusing.

    Tool Count5/5

    Ten tools is well scoped for a toolshed server covering registry search, source management, harness introspection, skill installation, and MCP proxying. Each tool appears to earn its place without obvious redundancy.

    Completeness3/5

    The surface covers search, read, source addition, skill installation, harness listing, and proxy discovery/calls, but notable lifecycle gaps remain: no remove/uninstall/refresh operations and no single-corpus search even though search_library is referenced as a contrasting tool. These omissions could cause dead ends for agents following the descriptions.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Enables AI assistants to search, discover, and get recommendations from 20,000+ skills, tools, agents, rules, and MCP servers.
      5
      28 npm
      1
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables searching and retrieving details of 41,000+ agent skills, MCP servers, Claude Code plugins, and agentic loops from any MCP-capable agent.
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables agents to search a lightweight catalog, inspect permissions, lazily start trusted MCP servers, and call child tools without keeping all schemas in context. It also loads approved skills on demand and routes third-party additions through a human approval queue.
      1
      103 npm
      1
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Enables coding agents to search an index of 22k+ MCP servers, agent skills and coding-agent plugins directly from chat, returning matches with stars, install commands and page links, plus trending repos and curated best-of topic lists. Read-only, no API key required, usable via a hosted HTTP endpoint or locally over stdio.
      4
      MIT