toolcapsule 0.1.0-alpha.12 → 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:
 
@@ -85,6 +85,8 @@ AI-first onboarding: install the ToolCapsule Skill into your coding agent, then
 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
@@ -222,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

package/docs/comparison.md

@@ -0,0 +1,69 @@
+# Comparison: ToolCapsule, native MCP, lazy-mcp, and MCP-to-Skill generators
+
+ToolCapsule is not a replacement for MCP. It is an AI-first workflow manager for heavy MCP tools.
+
+It overlaps with lazy MCP proxies and MCP-to-Skill generators, but the product shape is different: ToolCapsule inventories existing MCPs, links selected heavy servers into Agent Skills, keeps payloads in files, and records runs for patch-and-retry recovery.
+
+## Summary
+
+| Approach | Best for | What the agent sees | Main trade-off |
+|---|---|---|---|
+| Native MCP | Small, frequent tools | Full MCP tools exposed by the host | Heavy servers can add context and retry cost |
+| `lazy-mcp` style proxy | Aggregating many MCP servers behind a few meta-tools | Meta-tools such as list/describe/invoke | Requires adding a proxy MCP server and meta-tool calling discipline |
+| `mcp2skill` / `mcp-to-skill` style generators | One-time conversion of an MCP server into a Skill folder | Generated Skill and local executor/config | Often copies config into the Skill and is more generator-oriented |
+| ToolCapsule | Heavy SaaS/document/workflow MCPs used by AI coding agents | Official ToolCapsule Skill plus generated MCP-specific Skills with tool summaries | Requires `tcap` CLI for file-first calls and run artifacts |
+
+## Native MCP vs ToolCapsule
+
+Native MCP is the source of truth. ToolCapsule keeps it that way.
+
+The difference is workflow:
+
+- native MCP exposes tools directly to the host;
+- ToolCapsule lets the agent inventory MCPs, enable selected heavy ones as Skills, and call them through local files;
+- failed calls become patchable run artifacts instead of regenerated prompts.
+
+Use native MCP directly for small, high-frequency tools. Use ToolCapsule for heavy, low-frequency, document/workflow-oriented MCPs.
+
+## `lazy-mcp` style proxy vs ToolCapsule
+
+`lazy-mcp` is a client-agnostic MCP proxy. It aggregates MCP servers and exposes a small number of meta-tools such as list, describe, and invoke.
+
+ToolCapsule is not a proxy. It is a Skill and file workflow:
+
+- no replacement MCP proxy is required;
+- existing MCP configs can be linked instead of copied;
+- generated Skills include compact tool summaries;
+- calls use `@args.json` and saved run directories;
+- retry is done by patching local artifacts.
+
+Use a proxy when you want one MCP endpoint that aggregates many servers. Use ToolCapsule when you want the coding agent to manage heavy MCP workflows through Skills and files.
+
+## `mcp2skill` / `mcp-to-skill` generators vs ToolCapsule
+
+MCP-to-Skill generators convert a server into a Skill folder. That overlaps with one part of ToolCapsule.
+
+ToolCapsule adds a broader workflow:
+
+- AI-first onboarding via `npx skills add RainSunMe/toolcapsule --skill toolcapsule`;
+- `tcap mcp list` inventory across workspace, user, and ToolCapsule profiles;
+- `tcap mcp enable <server> --as <profile>` for selected heavy servers;
+- linked profiles by default, so private MCP URLs are not copied into generated Skills;
+- generated Skills with embedded tool summaries;
+- file-first calls through `tcap call <profile> <tool> @args.json --save-run`;
+- run artifacts under `.toolcapsule/runs/<profile>/<run-id>/`;
+- deterministic patch-and-retry.
+
+Use a generator when you only need a static Skill folder. Use ToolCapsule when you need an ongoing workflow for discovery, enabling, calling, auditing, and retrying heavy MCP tools.
+
+## Positioning
+
+ToolCapsule should be described as:
+
+> AI-first workflow manager for heavy MCP tools.
+
+Expanded:
+
+> ToolCapsule inventories your existing MCPs, turns selected heavy servers into lazy Agent Skills, and keeps calls file-first with auditable runs and patch-and-retry recovery.
+
+Related terms such as lazy MCP, MCP-to-Skill, and Agent Skills for MCP are useful search terms, but ToolCapsule is broader than a proxy or one-shot Skill generator.

package/docs/concept.md

@@ -1,6 +1,6 @@
 # Concept
 
-**ToolCapsule** is an MCP-to-Skill workflow layer for heavy MCP tools.
+**ToolCapsule** is an AI-first workflow manager for heavy MCP tools.
 
 MCP connects agents to tools. Skills package repeatable agent workflows. ToolCapsule sits between them: it keeps MCP as the source of truth, but turns schema-heavy tools into compact, lazy-loaded, file-first Agent Skills.
 

package/docs/hero-copy.md

@@ -4,7 +4,7 @@ Heavy MCP tools don't belong in your prompt.
 
 Put them in a 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 tools into lightweight, lazy-loaded Agent Skills, and keeps calls file-first with patch-and-retry recovery.
 
 If you are searching for lazy MCP, ToolCapsule is the workflow: keep MCP as the capability layer, expose an Agent Skill as the workflow layer, and load schemas only when needed.
 

package/docs/launch.md

@@ -2,15 +2,15 @@
 
 ## 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.
 
@@ -36,7 +36,7 @@ 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:
 

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.
 

package/llms.txt

@@ -1,6 +1,6 @@
 # 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.
 
@@ -24,23 +24,11 @@ Short command:
 tcap --help
 ```
 
-## Install the Agent Skill
-
-Inside a workspace:
-
-```bash
-tcap install-skill
-```
-
-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:
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "toolcapsule",
-  "version": "0.1.0-alpha.12",
-  "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",