toolcapsule 0.1.0-alpha.1 → 0.1.0-alpha.11

package/README.md

@@ -5,14 +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)
 
-> Heavy MCP tools don't belong in your prompt. Put them in a ToolCapsule.
+> MCP-to-Skill for heavy MCP tools.
 
-**ToolCapsule** turns heavy MCP servers into lightweight, lazy-loaded, file-first **Agent Skills** with patch-and-retry workflows.
+**ToolCapsule** turns heavy MCP servers into lightweight, lazy-loaded, file-first **Agent Skills** 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.
 
 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
 → compact Agent Skill
 → local args/content files
 → auditable tool runs
@@ -31,6 +34,36 @@ But large MCP servers can be expensive in agent contexts:
 - failed tool calls force the model to regenerate the whole call.
 
 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
+
+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.
+
+This is the practical version of a lazy MCP workflow:
+
+- MCP remains the protocol and source of truth;
+- Skills become the agent-facing workflow;
+- large payloads move into local files;
+- failed calls become patchable artifacts instead of regenerated prompts.
+
+## Import your existing MCP setup
+
+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
+```
+
+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
+.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`.
 
 ## What is a ToolCapsule?
 
@@ -47,11 +80,13 @@ Instead of making the model hold everything in the prompt, ToolCapsule stores he
 ```bash
 npm i -g toolcapsule
 
-toolcapsule init feishu --url https://mcp.example.com/mcp/xxx
+toolcapsule install-skill
+toolcapsule import --dry-run
+toolcapsule import --name feishu --target claude
 toolcapsule tools feishu --brief
 toolcapsule schema feishu create-doc
 toolcapsule call feishu create-doc @args.json --save-run
-toolcapsule retry runs/2026-06-06T10-00-00-000Z
+toolcapsule retry .toolcapsule/runs/feishu/2026-06-06T10-00-00-000Z
 ```
 
 Short alias:
@@ -64,11 +99,14 @@ tcap call feishu create-doc @args.json --save-run
 ## What it generates
 
 ```text
-.github/skills/feishu-mcp/
+.claude/skills/feishu-mcp/
   SKILL.md                  # lightweight Agent Skill entrypoint
   toolcapsule.config.json   # MCP transport/profile config
   scripts/README.md
-  runs/                     # auditable tool call records
+
+.toolcapsule/
+  profiles/feishu.json      # local MCP profile
+  runs/feishu/              # auditable tool call records
 ```
 
 This lets your agent discover the Skill instead of carrying the full MCP schema in every turn.
@@ -95,7 +133,7 @@ toolcapsule call feishu create-doc @args.json --save-run
 # 2. Patch args.json or content.md
 
 # 3. Retry deterministically
-toolcapsule retry runs/2026-06-06T10-00-00-000Z
+toolcapsule retry .toolcapsule/runs/feishu/2026-06-06T10-00-00-000Z
 ```
 
 This is especially useful for MCP tools that create documents, tickets, pages, dashboards, reports, or batch operations.
@@ -113,8 +151,12 @@ Results vary by MCP server, model, and host.
 ## CLI
 
 ```text
-toolcapsule init <name> --url <remote-mcp-url>
-toolcapsule init <name> --command <stdio-command> --arg <arg>
+toolcapsule init <name> --url <remote-mcp-url> --target claude
+toolcapsule init <name> --command <stdio-command> --arg <arg> --target claude
+toolcapsule install-skill --target claude
+toolcapsule import --dry-run
+toolcapsule import --name <server> --target claude
+toolcapsule import --all --target all
 toolcapsule tools <profile> --brief
 toolcapsule describe <profile> <tool> --brief
 toolcapsule schema <profile> <tool>
@@ -146,12 +188,15 @@ Early alpha. APIs may change before v1.0.
 
 - [Concept](docs/concept.md)
 - [Architecture](docs/architecture.md)
+- [Import existing MCP configuration](docs/importing-mcp.md)
 - [Patch and retry](docs/patch-and-retry.md)
 - [Benchmark methodology](docs/benchmark-methodology.md)
 - [Releasing](docs/releasing.md)
 - [Launch notes](docs/launch.md)
+- [Screenshots and recordings](docs/screenshots.md)
 - [Next steps](docs/next-steps.md)
 - [Release checklist](docs/release-checklist.md)
+- [Agent tool compatibility research](docs/agent-tool-compatibility.md)
 - [Roadmap](ROADMAP.md)
 
 ## License