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

package/docs/importing-mcp.md

@@ -6,17 +6,42 @@ This is the fastest onboarding path when a user already has MCP working in Claud
 
 ## Quick start
 
+AI-first onboarding starts by installing the ToolCapsule Skill, not the CLI:
+
+```bash
+npx skills add RainSunMe/toolcapsule --skill toolcapsule
+```
+
+For non-interactive installation into Claude Code:
+
 ```bash
-tcap import --dry-run
-tcap import --name <server> --target claude
+npx skills add RainSunMe/toolcapsule --skill toolcapsule --agent claude-code --yes
+```
+
+Then ask the agent to use the ToolCapsule Skill to inspect MCPs and capsule selected heavy servers.
+
+Manual CLI flow:
+
+```bash
+tcap mcp list --include-user
+tcap mcp enable <server> --as <profile> --target claude
+```
+
+The newer inventory-oriented flow is:
+
+```bash
+tcap mcp list --include-user
+tcap mcp enable <server> --as <profile> --target claude
 ```
 
 To write skills for multiple agents:
 
 ```bash
-tcap import --name <server> --target all
+tcap mcp enable <server> --as <profile> --target all
 ```
 
+Use `--as` when the native MCP server name is generic, for example `tcap import --name docs --as feishu`.
+
 ## What gets created
 
 An MCP-to-Skill import keeps MCP as the capability layer and creates a Skill as the agent-facing workflow layer.
@@ -24,7 +49,7 @@ An MCP-to-Skill import keeps MCP as the capability layer and creates a Skill as
 For an imported server named `github`, ToolCapsule writes:
 
 ```text
-.toolcapsule/profiles/github.json
+~/.toolcapsule/profiles/github.json
 .claude/skills/github-mcp/SKILL.md
 ```
 
@@ -90,7 +115,11 @@ ToolCapsule stores the reference, not the resolved secret value.
 
 - Run `--dry-run` first.
 - Use `--include-user` only when you want ToolCapsule to inspect personal MCP config.
-- Do not commit generated profiles if they contain private endpoints, document IDs, tokens, or machine-specific paths.
+- Imported profiles are stored under `~/.toolcapsule/profiles/` by default so MCP connections can be reused across projects.
+- Imports link to the original MCP config by default instead of copying private endpoints.
+- Use `--copy` when you want a stable snapshot profile that no longer depends on the source MCP config file.
+- Use `--local` only when a profile should be stored in the current workspace under `.toolcapsule/profiles/`.
+- Do not commit local generated profiles if they contain private endpoints, document IDs, tokens, or machine-specific paths.
 - Keep `.toolcapsule/`, generated skills, and run artifacts under review before sharing.
 - Transport logs are quiet by default. Set `TOOLCAPSULE_DEBUG=1` only when debugging.
 
@@ -99,8 +128,8 @@ ToolCapsule stores the reference, not the resolved secret value.
 ### Import one server for Claude Code
 
 ```bash
-tcap import --dry-run
-tcap import --name notion --target claude
+tcap mcp list --include-user
+tcap mcp enable notion --target claude
 tcap tools notion --brief
 ```
 

package/docs/launch.md

@@ -2,29 +2,30 @@
 
 ## One-line pitch
 
-MCP-to-Skill for heavy MCP tools.
+AI-first workflow manager for heavy MCP tools.
 
 ## Short pitch
 
-ToolCapsule turns schema-heavy MCP servers into lightweight, lazy-loaded Agent Skills with file-first calls and patch-and-retry recovery. If you are looking for lazy MCP, this is the workflow layer.
+ToolCapsule inventories existing MCPs, turns selected heavy servers into lazy Agent Skills, and keeps calls file-first with patch-and-retry recovery.
 
 ## Announcement draft
 
-MCP is becoming the standard way to connect agents to tools. Skills are becoming the standard way to package repeatable agent workflows. ToolCapsule connects the two: MCP-to-Skill for heavy tools.
+MCP is becoming the standard way to connect agents to tools. Skills are becoming the standard way to package repeatable agent workflows. ToolCapsule connects the two as an AI-first workflow manager for heavy MCP tools.
 
 Large MCP servers can quietly eat your context window with long tool descriptions and schemas. ToolCapsule keeps MCP as the capability layer and turns heavy tools into compact, lazy-loaded Agent Skills. Large payloads live in files, every call can be recorded, and failed calls can be patched and retried without asking the model to regenerate everything.
 
 Install:
 
 ```bash
-npm i -g toolcapsule
+npx skills add RainSunMe/toolcapsule --skill toolcapsule
 ```
 
 Try:
 
 ```bash
-tcap import --dry-run
-tcap import --name feishu --target claude
+npm i -g toolcapsule
+tcap mcp list --include-user
+tcap mcp enable docs --as feishu --target claude
 tcap tools feishu --brief
 tcap call feishu create-doc @args.json --save-run
 ```
@@ -35,13 +36,13 @@ New onboarding angle:
 
 Search angle:
 
-> Lazy MCP, MCP to Skill, MCP-to-Skill, Agent Skills for MCP tools — all describe the workflow ToolCapsule implements.
+> Lazy MCP, MCP to Skill, MCP-to-Skill, Agent Skills for MCP tools — these are related search terms, but ToolCapsule is broader: inventory, enable, Skill generation, file-first calls, and patch-and-retry.
 
 Short demo:
 
 ```bash
-tcap import --dry-run
-tcap import --name github --target all
+tcap mcp list --include-user
+tcap mcp enable github --target all
 ```
 
 ## Suggested screenshot checklist
@@ -49,15 +50,15 @@ tcap import --name github --target all
 Ask a human/function-caller to capture:
 
 1. Hero section at `https://toolcapsule.studio` or `https://toolcapsule.vercel.app`.
-2. Terminal showing `tcap import --dry-run` finding an existing MCP server.
+2. Terminal showing `tcap mcp list --include-user` finding existing MCP servers.
 3. Terminal showing `tcap tools feishu --brief`.
 4. Terminal showing a saved run directory.
 5. Before/after graphic: native MCP schema in prompt vs ToolCapsule local artifacts.
 
 ## Suggested GIF flow
 
-1. Run `tcap import --dry-run`.
-2. Run `tcap import --name ... --target claude`.
+1. Run `tcap mcp list --include-user`.
+2. Run `tcap mcp enable ... --as ... --target claude`.
 3. Run `tcap call ... --save-run`.
 4. Show failure or saved run artifacts.
 5. Patch `args.json`.

package/docs/next-steps.md

@@ -2,7 +2,7 @@
 
 ToolCapsule has reached a public alpha loop: GitHub repository, Vercel site, npm package, release workflow, and project skill are in place.
 
-The public positioning is now: MCP-to-Skill for heavy MCP tools. Keep future docs, demos, and releases aligned with lazy MCP, lazy-loaded Agent Skills, and Agent Skills for MCP search intent.
+The public positioning is now: AI-first workflow manager for heavy MCP tools. Keep future docs, demos, and releases aligned with MCP inventory, lazy Agent Skills, file-first calls, and patch-and-retry.
 
 This document tracks what should happen next.
 
@@ -62,8 +62,8 @@ Add a better release note with:
 Initial support exists:
 
 ```bash
-tcap import --dry-run
-tcap import --name <server> --target claude
+tcap mcp list --include-user
+tcap mcp enable <server> --as <profile> --target claude
 tcap import --all --target all
 ```
 
@@ -201,7 +201,8 @@ Because ToolCapsule can call tools, store artifacts, and connect to MCP servers,
 
 - Do not commit secrets.
 - Run artifacts may contain sensitive data.
-- `.toolcapsule/` is ignored by default and stores local profiles plus run artifacts.
+- `.toolcapsule/` is ignored by default and stores workspace-local run artifacts plus optional `--local` profiles.
+- User-level MCP profiles live under `~/.toolcapsule/profiles/` by default.
 - Generated files should be reviewed before sharing.
 - Enterprise users should audit local artifacts.
 

package/examples/feishu/README.md

@@ -13,10 +13,13 @@ tcap init feishu --url https://mcp.feishu.cn/mcp/your-endpoint
 This creates:
 
 ```text
-.toolcapsule/profiles/feishu.json
+~/.toolcapsule/profiles/feishu.json
 .github/skills/feishu-mcp/SKILL.md
 ```
 
+Use `--local` if the profile should be stored in this workspace under `.toolcapsule/profiles/` instead.
+Use `--copy` with `tcap import` if you want ToolCapsule to snapshot the MCP transport instead of linking the original MCP config.
+
 ## 2. Discover tools briefly
 
 ```bash

package/llms.txt

@@ -1,38 +1,34 @@
 # ToolCapsule
 
-ToolCapsule is MCP-to-Skill for heavy MCP tools. It turns schema-heavy MCP servers into lightweight, lazy-loaded Agent Skills with file-first calls and patch-and-retry recovery.
+ToolCapsule is an AI-first workflow manager for heavy MCP tools. It inventories existing MCPs, turns selected heavy servers into lazy Agent Skills, and keeps calls file-first with patch-and-retry recovery.
 
 Use it when an AI agent needs a lazy MCP workflow: operate a heavy MCP server without carrying full tool schemas in every prompt.
 
 ## Install
 
+AI-first install:
+
 ```bash
-npm install -g toolcapsule
+npx skills add RainSunMe/toolcapsule --skill toolcapsule
 ```
 
-Short command:
+The ToolCapsule Skill then instructs the agent to install the CLI if needed:
 
 ```bash
-tcap --help
+npm install -g toolcapsule
 ```
 
-## Install the Agent Skill
-
-Inside a workspace:
+Short command:
 
 ```bash
-tcap install-skill
+tcap --help
 ```
 
-This creates:
-
-```text
-.github/skills/toolcapsule/SKILL.md
-```
+Note: `npx skills add toolcapsule` is not enough today because the `skills` CLI treats a bare value as a git source. Use `RainSunMe/toolcapsule`.
 
 ## Convert an MCP server into a Skill workflow
 
-This is the MCP-to-Skill step: keep MCP as the capability layer and generate an Agent Skill as the workflow layer.
+This is the ToolCapsule enable step: keep MCP as the capability layer and generate an Agent Skill as the workflow layer.
 
 Remote MCP:
 
@@ -67,7 +63,7 @@ tcap call <name> <tool> @args.json --save-run
 ## Retry after patching local files
 
 ```bash
-tcap retry runs/<run-id>
+tcap retry .toolcapsule/runs/<profile>/<run-id>
 ```
 
 ## Benchmark schema footprint

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "toolcapsule",
-  "version": "0.1.0-alpha.11",
-  "description": "MCP-to-Skill for lazy-loaded, patchable Agent Skills from heavy MCP tools.",
+  "version": "0.1.0-alpha.13",
+  "description": "AI-first workflow manager for heavy MCP tools with lazy Agent Skills and patchable runs.",
   "type": "module",
   "bin": {
     "toolcapsule": "dist/cli.js",
@@ -12,6 +12,7 @@
     "README.md",
     "LICENSE",
     "docs",
+    "skills",
     "examples",
     "llms.txt"
   ],

package/skills/toolcapsule/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: toolcapsule
+description: 'Use when: discovering MCP servers, turning heavy MCP tools into lazy Agent Skills, installing ToolCapsule, generating MCP-specific Skills, calling MCP tools through local files, or using patch-and-retry recovery.'
+argument-hint: 'MCP server, profile name, target agent, args file, or retry task'
+---
+
+# ToolCapsule
+
+ToolCapsule is not a replacement for MCP. It is a workflow layer for heavy MCP tools: discover MCP servers, turn selected ones into lazy Agent Skills, keep large payloads in files, and retry failed calls by patching artifacts.
+
+## Install
+
+This Skill is intended to be installed with the open `skills` CLI:
+
+```bash
+npx skills add RainSunMe/toolcapsule --skill toolcapsule
+```
+
+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
+```
+
+After this Skill is active, check whether the ToolCapsule CLI is available. If `toolcapsule` or `tcap` is missing, install it:
+
+```bash
+npm install -g toolcapsule
+```
+
+Verify:
+
+```bash
+tcap --version
+```
+
+## Core workflow for agents
+
+1. Inventory MCP servers without exposing secrets:
+
+```bash
+tcap mcp list
+# If the user asks to inspect user-level configs too:
+tcap mcp list --include-user
+```
+
+2. Pick heavy MCP servers that should not stay in the prompt every turn. Prefer document, SaaS, ticket, wiki, dashboard, or batch tools.
+
+3. Enable ToolCapsule for a selected native MCP. Use `--as` when the original server name is generic:
+
+```bash
+tcap mcp enable <native-server-name> --as <profile-name> --target claude
+```
+
+This links to the original MCP config by default. Use `--copy` only when the user wants a stable snapshot independent of the source MCP config:
+
+```bash
+tcap mcp enable <native-server-name> --as <profile-name> --copy --target claude
+```
+
+4. If there is no existing MCP config, create a ToolCapsule profile directly:
+
+```bash
+tcap init <profile-name> --url <remote-mcp-url> --target claude
+# or
+tcap init <profile-name> --command <stdio-command> --arg <arg> --target claude
+```
+
+5. Use generated MCP-specific Skills. They should contain a tool summary table. Only run schema lookup when needed:
+
+```bash
+tcap schema <profile-name> <tool>
+```
+
+6. For calls, prefer local files:
+
+```bash
+tcap call <profile-name> <tool> @args.json --save-run
+```
+
+7. If a call fails, patch artifacts and retry:
+
+```bash
+tcap retry .toolcapsule/runs/<profile-name>/<run-id>
+```
+
+## Optional native disable
+
+Only disable native MCP configs when the user explicitly wants to stop the host from loading a heavy MCP directly.
+
+Always dry-run first:
+
+```bash
+tcap mcp disable <native-server-name> --native
+```
+
+Apply only after user confirmation:
+
+```bash
+tcap mcp disable <native-server-name> --native --yes
+```
+
+Do not modify managed or enterprise MCP configs.
+
+## Safety
+
+- Never print private MCP URLs, tokens, API keys, user IDs, or document IDs unless the user explicitly asks.
+- Prefer linked profiles over copied snapshots to avoid duplicating private endpoints.
+- Use `--include-user` only when the user agrees to inspect user-level MCP configs.
+- Keep `.toolcapsule/` local; it may contain run artifacts with sensitive request/response data.
+- Use `TOOLCAPSULE_DEBUG=1` only for debugging.
+
+## Target paths
+
+- `--target claude` → `.claude/skills/<name>-mcp/`
+- `--target copilot` → `.github/skills/<name>-mcp/`
+- `--target opencode` → `.opencode/skills/<name>-mcp/`
+- `--target agents` → `.agents/skills/<name>-mcp/`
+- `--target all` → all of the above
+
+MCP profiles are stored under `~/.toolcapsule/profiles/` by default. Workspace run artifacts are stored under `.toolcapsule/runs/<profile>/`.