Toolcapsule

npm version CI License: MIT GitHub Repo stars

Convert MCP servers into lazy Agent Skills. MCP stays the capability layer; Skills become the agent-facing workflow layer.

ToolCapsule takes a heavy MCP server, fetches its tool schemas, and generates a compact Agent Skill with everything the agent needs to call those tools through local files.

MCP server → tcap init → ~/.toolcapsule/profiles/<name>.json + SKILL.md

Why

Large MCP servers bloat agent context: every tool description and schema is visible every turn, even when no tool call is needed. ToolCapsule moves that payload into a Skill the agent reads on demand, and moves call arguments into /tmp files instead of inline JSON.

Quick start

Install the ToolCapsule Skill into your agent:

npx skills add RainSunMe/toolcapsule --skill toolcapsule

The agent will read the Skill, install the CLI, and register your MCP servers. Or do it manually:

npm install -g toolcapsule
tcap init feishu --url https://mcp.feishu.cn/mcp/xxx --target claude

The tcap alias is equivalent to toolcapsule.

CLI

tcap init   <name> --url <url> | --command <cmd> [--arg <arg>] [--target <target>]
tcap call   <profile> <tool> '{"key":"value"}' | @/tmp/args.json
tcap tools  <profile> [--brief | --names | --json]
tcap schema <profile> <tool>

Supported targets: agents (default), copilot, claude, opencode, all.

Workflow

# 1. Register an MCP server — creates profile + Skill
tcap init feishu --url https://mcp.feishu.cn/mcp/xxx --target claude

# 2. Agent reads .claude/skills/feishu-mcp/SKILL.md
#    → sees tool summaries, usage instructions

# 3. Look up details on demand
tcap tools feishu                # compact one-line list
tcap schema feishu create-doc    # compact schema for one tool

# 4. Call with inline JSON for simple args
tcap call feishu fetch-doc '{"doc_id":"https://mi.feishu.cn/docx/..."}'

#    Or call with args in /tmp file for larger payloads
tcap call feishu create-doc @/tmp/tcap-feishu-create-doc.json

# 5. If a file-based call fails — edit /tmp file and re-run step 4

What gets created

~/.toolcapsule/
  profiles/feishu.json          ← transport config (never commit)

.claude/skills/feishu-mcp/
  SKILL.md                      ← Agent Skill (safe to commit)

Auth

ToolCapsule detects authentication requirements automatically:

• URL-embedded tokens (e.g. Feishu): just pass the full URL to init
• Header tokens (e.g. API keys): edit ~/.toolcapsule/profiles/<name>.json to add "headers": { "Authorization": "Bearer <token>" }
• OAuth (e.g. Figma): init auto-discovers the OAuth endpoint and shows the authorization URL

Who is it for

Heavy MCP servers that are:

• schema-heavy (many tools, long descriptions)
• document/workflow oriented
• used occasionally rather than every turn
• carrying large payloads

Examples: Feishu/Lark, Notion, Figma, Jira, Linear, Confluence, Google Docs, GitHub management tools, internal SaaS MCPs.

Documentation

• Concept
• Architecture
• Comparison
• Releasing
• Release checklist
• Roadmap

License

MIT