toolcapsule 0.1.0-alpha.11 → 0.1.0-alpha.13

package/README.md

@@ -5,17 +5,17 @@
 [![License: MIT](https://img.shields.io/badge/license-MIT-black?style=flat-square)](LICENSE)
 [![GitHub Repo stars](https://img.shields.io/github/stars/RainSunMe/toolcapsule?style=flat-square)](https://github.com/RainSunMe/toolcapsule)
 
-> MCP-to-Skill for heavy MCP tools.
+> AI-first workflow manager for heavy MCP tools.
 
-**ToolCapsule** turns heavy MCP servers into lightweight, lazy-loaded, file-first **Agent Skills** with saved runs and patch-and-retry recovery.
+**ToolCapsule** inventories your MCPs, turns heavy ones into lightweight, lazy-loaded, file-first **Agent Skills**, and keeps tool calls auditable with saved runs and patch-and-retry recovery.
 
-If you are looking for **lazy MCP**, **MCP to Skill**, **MCP-to-Skill**, or **Agent Skills for MCP tools**, ToolCapsule is built for that workflow.
+If you are looking for **lazy MCP**, **MCP to Skill**, **MCP-to-Skill**, or **Agent Skills for MCP tools**, ToolCapsule covers that workflow without replacing MCP.
 
 It is not a replacement for MCP or Skills. It is the missing workflow layer between them:
 
 ```text
 Heavy MCP server
-→ MCP-to-Skill workflow layer
+→ AI-first ToolCapsule workflow layer
 → compact Agent Skill
 → local args/content files
 → auditable tool runs
@@ -36,9 +36,9 @@ But large MCP servers can be expensive in agent contexts:
 ToolCapsule keeps the MCP server as the source of truth, but exposes it through a lightweight Skill and local artifacts.
 Transport logs are quiet by default so remote MCP URLs are not printed during normal use. Set `TOOLCAPSULE_DEBUG=1` only when debugging.
 
-## MCP-to-Skill and lazy MCP
+## AI-first MCP workflow
 
-ToolCapsule is an **MCP-to-Skill workflow layer**. It imports existing MCP configurations and generates Agent Skills that let agents lazy-load MCP schemas only when needed.
+ToolCapsule is an **AI-first workflow manager for heavy MCP tools**. It inventories existing MCP configurations, links selected servers into ToolCapsule profiles, and generates Agent Skills that let agents lazy-load MCP schemas only when needed.
 
 This is the practical version of a lazy MCP workflow:
 
@@ -52,18 +52,20 @@ This is the practical version of a lazy MCP workflow:
 Already configured MCP in Claude Code, GitHub Copilot / VS Code, OpenCode, Gemini CLI, or Cursor? Import it instead of retyping URLs and commands:
 
 ```bash
-tcap import --dry-run
-tcap import --name github --target claude
+tcap mcp list --include-user
+tcap mcp enable docs --as feishu --target claude
 ```
 
 ToolCapsule scans common workspace MCP config files such as `.mcp.json`, `.vscode/mcp.json`, `opencode.json`, `.gemini/settings.json`, and `.cursor/mcp.json`, then creates:
 
 ```text
-.toolcapsule/profiles/<server>.json
+~/.toolcapsule/profiles/<server>.json
 .claude/skills/<server>-mcp/SKILL.md
 ```
 
-Use `--target copilot`, `--target opencode`, `--target agents`, or `--target all` to write skills for other agents. User-level MCP configs are only inspected when you opt in with `--include-user`.
+MCP profiles are user-level by default because MCP server connections are usually reused across projects. Use `--local` to store a profile in `.toolcapsule/profiles/` for the current workspace. Use `--target copilot`, `--target opencode`, `--target agents`, or `--target all` to write skills for other agents. User-level MCP configs are only inspected when you opt in with `--include-user`.
+
+Imports link back to the original MCP config by default so ToolCapsule does not duplicate private MCP URLs. Use `--copy` when you want a stable ToolCapsule snapshot profile.
 
 ## What is a ToolCapsule?
 
@@ -77,12 +79,32 @@ Instead of making the model hold everything in the prompt, ToolCapsule stores he
 
 ## Quick start
 
+AI-first onboarding: install the ToolCapsule Skill into your coding agent, then ask the agent to inventory MCPs and capsule the heavy ones.
+
+```bash
+npx skills add RainSunMe/toolcapsule --skill toolcapsule
+```
+
+`npx skills add toolcapsule` is not enough today because the `skills` CLI treats a bare value as a git source. Use the GitHub shorthand above.
+
+For a specific agent or global install:
+
+```bash
+npx skills add RainSunMe/toolcapsule --skill toolcapsule --agent claude-code
+npx skills add RainSunMe/toolcapsule --skill toolcapsule --global --agent claude-code
+```
+
+Then tell your agent:
+
+> Use the ToolCapsule Skill. Scan my MCP servers, pick the heavy ones, and turn them into lazy ToolCapsule Skills.
+
+Manual CLI workflow:
+
 ```bash
 npm i -g toolcapsule
 
-toolcapsule install-skill
-toolcapsule import --dry-run
-toolcapsule import --name feishu --target claude
+toolcapsule mcp list --include-user
+toolcapsule mcp enable docs --as feishu --target claude
 toolcapsule tools feishu --brief
 toolcapsule schema feishu create-doc
 toolcapsule call feishu create-doc @args.json --save-run
@@ -101,12 +123,13 @@ tcap call feishu create-doc @args.json --save-run
 ```text
 .claude/skills/feishu-mcp/
   SKILL.md                  # lightweight Agent Skill entrypoint
-  toolcapsule.config.json   # MCP transport/profile config
   scripts/README.md
 
+~/.toolcapsule/
+  profiles/feishu.json      # user-level MCP profile, reusable across projects
+
 .toolcapsule/
-  profiles/feishu.json      # local MCP profile
-  runs/feishu/              # auditable tool call records
+  runs/feishu/              # workspace-local auditable tool call records
 ```
 
 This lets your agent discover the Skill instead of carrying the full MCP schema in every turn.
@@ -153,9 +176,13 @@ Results vary by MCP server, model, and host.
 ```text
 toolcapsule init <name> --url <remote-mcp-url> --target claude
 toolcapsule init <name> --command <stdio-command> --arg <arg> --target claude
-toolcapsule install-skill --target claude
+npx skills add RainSunMe/toolcapsule --skill toolcapsule
+toolcapsule mcp list --include-user
+toolcapsule mcp enable <server> --as <profile> --target claude
+toolcapsule mcp disable <profile>
+toolcapsule mcp disable <server> --native
 toolcapsule import --dry-run
-toolcapsule import --name <server> --target claude
+toolcapsule import --name <server> --as <profile> --target claude
 toolcapsule import --all --target all
 toolcapsule tools <profile> --brief
 toolcapsule describe <profile> <tool> --brief
@@ -197,6 +224,7 @@ Early alpha. APIs may change before v1.0.
 - [Next steps](docs/next-steps.md)
 - [Release checklist](docs/release-checklist.md)
 - [Agent tool compatibility research](docs/agent-tool-compatibility.md)
+- [Comparison with native MCP, lazy-mcp, and MCP-to-Skill generators](docs/comparison.md)
 - [Roadmap](ROADMAP.md)
 
 ## License