@apicircle/mcp-server 1.0.1 → 1.0.2

package/LICENSE

@@ -1,110 +1,110 @@
-API Circle Studio License
-Custom Source-Available License, v1.0
-
-Copyright (c) 2026 Deva Prakash ("Licensor")
-
-The source code in this repository ("the Software") is made available for
-the purposes of transparency, security review, contribution, and personal
-evaluation. This is NOT an open-source license as defined by the Open
-Source Initiative.
-
-0. Definitions
-
-   "Commercial Use" means any use of the Software that is intended for
-   or directed toward commercial advantage or monetary compensation,
-   whether direct or indirect, including without limitation:
-
-   (a) using the Software to build, test, develop, deploy, or operate
-       any product, service, application, or system that is sold,
-       licensed, hosted, distributed, or otherwise made available to
-       any third party for a fee or other consideration;
-   (b) using the Software in the course of paid employment, paid
-       consulting, paid contracting, freelance work, or any other
-       revenue-generating activity, regardless of whether the Software
-       itself is sold or transferred;
-   (c) using the Software internally within a for-profit organization
-       beyond the Evaluation Period defined below;
-   (d) integrating the Software, or any portion of it, into any tool,
-       pipeline, automation, or workflow that supports the commercial
-       operations of any business;
-   (e) using the Software to provide a hosted, managed, or embedded
-       service of any kind to a third party, whether free or paid.
-
-   "Non-Commercial Use" means any use that is not Commercial Use,
-   including personal hobby projects, individual learning, academic
-   research, classroom instruction, and good-faith contribution to
-   this repository.
-
-   "Evaluation Period" means a single, continuous period of up to
-   thirty (30) days during which a for-profit organization may
-   internally evaluate the Software at no charge. After the Evaluation
-   Period expires, any further use of the Software by that organization
-   constitutes Commercial Use and requires a separate commercial
-   license from the Licensor.
-
-1. Permitted Use
-
-   You may, without charge:
-
-   (a) view, read, and study the source code of the Software;
-   (b) run the Software, in source or compiled form, for your own
-       Non-Commercial Use, or for Commercial Use solely within the
-       Evaluation Period;
-   (c) submit improvements to the Software back to this repository via
-       pull request, subject to Section 3 (Contributions).
-
-2. Prohibited Use
-
-   Without prior written permission from the Licensor, you may NOT:
-
-   (a) make any Commercial Use of the Software, in whole or in part,
-       except during the Evaluation Period as defined in Section 0;
-   (b) redistribute the Software, in source or compiled form, whether
-       modified or unmodified, to any third party;
-   (c) sublicense, sell, rent, lease, or otherwise transfer the
-       Software or any rights granted herein;
-   (d) remove, obscure, or alter any copyright, trademark, attribution,
-       or license notice contained in the Software;
-   (e) use the names "API Circle", "API Circle Studio", or any related
-       logos or trademarks, except as required for accurate attribution.
-
-3. Contributions
-
-   By submitting any contribution (including but not limited to code,
-   documentation, or assets) to this repository, you grant the Licensor
-   a perpetual, worldwide, irrevocable, royalty-free, sublicensable
-   license to use, modify, distribute, and relicense your contribution
-   under any terms, including the terms of this license or any future
-   version thereof.
-
-4. No Trademark License
-
-   This license does not grant permission to use the trade names,
-   trademarks, service marks, or product names of the Licensor, except
-   as required for reasonable and customary use in describing the
-   origin of the Software.
-
-5. Termination
-
-   The rights granted in Section 1 terminate automatically if you
-   breach any term of this license. Upon termination, you must cease
-   all use of the Software and destroy all copies in your possession.
-
-6. Disclaimer of Warranty
-
-   THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
-   EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
-   MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, TITLE, AND
-   NON-INFRINGEMENT.
-
-7. Limitation of Liability
-
-   IN NO EVENT SHALL THE LICENSOR BE LIABLE FOR ANY CLAIM, DAMAGES, OR
-   OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT, OR
-   OTHERWISE, ARISING FROM, OUT OF, OR IN CONNECTION WITH THE SOFTWARE
-   OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
-
-8. Commercial Licensing
-
-   For commercial licensing, redistribution, or any use not permitted
-   under Section 1, contact: apicircle365@gmail.com
+API Circle Studio License
+Custom Source-Available License, v1.0
+
+Copyright (c) 2026 Deva Prakash ("Licensor")
+
+The source code in this repository ("the Software") is made available for
+the purposes of transparency, security review, contribution, and personal
+evaluation. This is NOT an open-source license as defined by the Open
+Source Initiative.
+
+0. Definitions
+
+   "Commercial Use" means any use of the Software that is intended for
+   or directed toward commercial advantage or monetary compensation,
+   whether direct or indirect, including without limitation:
+
+   (a) using the Software to build, test, develop, deploy, or operate
+       any product, service, application, or system that is sold,
+       licensed, hosted, distributed, or otherwise made available to
+       any third party for a fee or other consideration;
+   (b) using the Software in the course of paid employment, paid
+       consulting, paid contracting, freelance work, or any other
+       revenue-generating activity, regardless of whether the Software
+       itself is sold or transferred;
+   (c) using the Software internally within a for-profit organization
+       beyond the Evaluation Period defined below;
+   (d) integrating the Software, or any portion of it, into any tool,
+       pipeline, automation, or workflow that supports the commercial
+       operations of any business;
+   (e) using the Software to provide a hosted, managed, or embedded
+       service of any kind to a third party, whether free or paid.
+
+   "Non-Commercial Use" means any use that is not Commercial Use,
+   including personal hobby projects, individual learning, academic
+   research, classroom instruction, and good-faith contribution to
+   this repository.
+
+   "Evaluation Period" means a single, continuous period of up to
+   thirty (30) days during which a for-profit organization may
+   internally evaluate the Software at no charge. After the Evaluation
+   Period expires, any further use of the Software by that organization
+   constitutes Commercial Use and requires a separate commercial
+   license from the Licensor.
+
+1. Permitted Use
+
+   You may, without charge:
+
+   (a) view, read, and study the source code of the Software;
+   (b) run the Software, in source or compiled form, for your own
+       Non-Commercial Use, or for Commercial Use solely within the
+       Evaluation Period;
+   (c) submit improvements to the Software back to this repository via
+       pull request, subject to Section 3 (Contributions).
+
+2. Prohibited Use
+
+   Without prior written permission from the Licensor, you may NOT:
+
+   (a) make any Commercial Use of the Software, in whole or in part,
+       except during the Evaluation Period as defined in Section 0;
+   (b) redistribute the Software, in source or compiled form, whether
+       modified or unmodified, to any third party;
+   (c) sublicense, sell, rent, lease, or otherwise transfer the
+       Software or any rights granted herein;
+   (d) remove, obscure, or alter any copyright, trademark, attribution,
+       or license notice contained in the Software;
+   (e) use the names "API Circle", "API Circle Studio", or any related
+       logos or trademarks, except as required for accurate attribution.
+
+3. Contributions
+
+   By submitting any contribution (including but not limited to code,
+   documentation, or assets) to this repository, you grant the Licensor
+   a perpetual, worldwide, irrevocable, royalty-free, sublicensable
+   license to use, modify, distribute, and relicense your contribution
+   under any terms, including the terms of this license or any future
+   version thereof.
+
+4. No Trademark License
+
+   This license does not grant permission to use the trade names,
+   trademarks, service marks, or product names of the Licensor, except
+   as required for reasonable and customary use in describing the
+   origin of the Software.
+
+5. Termination
+
+   The rights granted in Section 1 terminate automatically if you
+   breach any term of this license. Upon termination, you must cease
+   all use of the Software and destroy all copies in your possession.
+
+6. Disclaimer of Warranty
+
+   THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+   EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+   MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, TITLE, AND
+   NON-INFRINGEMENT.
+
+7. Limitation of Liability
+
+   IN NO EVENT SHALL THE LICENSOR BE LIABLE FOR ANY CLAIM, DAMAGES, OR
+   OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT, OR
+   OTHERWISE, ARISING FROM, OUT OF, OR IN CONNECTION WITH THE SOFTWARE
+   OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+8. Commercial Licensing
+
+   For commercial licensing, redistribution, or any use not permitted
+   under Section 1, contact: apicircle365@gmail.com

package/README.md

@@ -4,48 +4,158 @@
 
 <h1 align="center">@apicircle/mcp-server</h1>
 
-Model Context Protocol server for [API Circle Studio](https://github.com/apicircle/studio). Exposes the workspace as a 71-tool catalog any [MCP-compatible AI client](https://modelcontextprotocol.io) can drive — Claude Desktop, Claude Code, ChatGPT, GitHub Copilot, Cursor, Continue, Cline, Zed, Windsurf, and more.
+<p align="center">
+  <strong>Give your AI assistant a real API client.</strong><br />
+  A Model Context Protocol server that exposes the API Circle Studio workspace as a <strong>71-tool catalog</strong> — so Claude, ChatGPT, Cursor, Copilot, and every other MCP client can read, author, mock, and run requests for you.
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@apicircle/mcp-server"><img src="https://img.shields.io/npm/v/@apicircle/mcp-server?color=cb3837&logo=npm" alt="npm version" /></a>
+  <img src="https://img.shields.io/badge/MCP%20tools-71-blueviolet" alt="71 MCP tools" />
+  <img src="https://img.shields.io/badge/transport-stdio-blue" alt="stdio transport" />
+  <img src="https://img.shields.io/badge/multi--workspace-yes-success" alt="Multi-workspace" />
+  <img src="https://img.shields.io/badge/node-%E2%89%A5%2020-brightgreen" alt="Node ≥ 20" />
+</p>
+
+---
+
+## What this gives your AI
+
+Most "AI + API client" integrations stop at autocompletion. This goes much
+further. When you wire `@apicircle/mcp-server` into Claude Desktop, Claude
+Code, ChatGPT, Cursor, Codex, Copilot, Continue, Cline, Zed, Windsurf — any
+MCP-compatible client — your assistant gains the ability to:
+
+- **Read your workspace.** Browse requests, folders, environments, plans,
+  and mock servers across **multiple workspaces** on the same machine.
+- **Author requests.** Create, rename, move, and delete requests / folders /
+  environments / assertions with prompt-driven, LLM-shaped JSON tools.
+- **Import specs.** Drop in an OpenAPI / Swagger / Postman / Insomnia / HAR /
+  cURL file and the assistant turns it into a typed collection.
+- **Generate code.** Emit working clients in **cURL, fetch, axios, Python
+  requests, Go, and Rust** for any request.
+- **Extract from your codebase.** Scan an Express, FastAPI, NestJS, or
+  Spring project and propose a request collection that mirrors the routes.
+- **Mock APIs.** Boot a real local mock server from an OpenAPI spec —
+  start, stop, and tear down — straight from the chat.
+- **Run + replay history.** List history runs, replay them, purge old ones.
+
+All without you leaving the conversation.
 
 ## Install
 
 ```bash
-# Globally for use as a stdio binary
+# The common case — install globally and wire as a stdio MCP server
 npm install -g @apicircle/mcp-server
 
-# Or as a dependency
+# Or as a library, when you're embedding the host in your own product
 npm install @apicircle/mcp-server
 ```
 
-## What's a "workspace folder"?
-
-`--workspace <dir>` points the server at a directory containing
-`workspace.synced.json` + `workspace.local.json`. **That directory is a
-git-cloned API Circle workspace repo** — created by the Desktop app's
-_Link to Git_ feature, then cloned with `git clone`:
+## Quick start
 
 ```bash
-git clone https://github.com/<you>/<your-workspace-repo>
-apicircle-mcp --workspace ./<your-workspace-repo>
+# Multi-workspace mode (default) — exposes every workspace on this machine
+apicircle-mcp
+
+# Single-workspace mode — point at a folder with a workspace.synced.json
+# (CI, a git-cloned workspace repo, etc.)
+apicircle-mcp --workspace /path/to/checkout-repo
 ```
 
-**Don't have a workspace repo yet?** Use the **Desktop or Web app** instead.
-Its workspace lives in browser storage (no folder needed), and the in-app
-**MCP panel** generates a ready-to-paste config snippet for every supported
-AI client — Claude Desktop, Cursor, Copilot, ChatGPT, and the rest — wired to
-the app's workspace directly. This binary is the headless equivalent for
-when you've outgrown the in-app flow.
+The server speaks JSON-RPC on stdin/stdout (logs to stderr). Plug it into
+your AI client per the
+[Connect your AI client](https://github.com/apicircle/studio/blob/main/docs/connect-your-ai-client.md)
+guide, or copy/paste the snippet generated by the desktop app's
+**MCP → How to Connect** panel.
 
-## Run as a binary
+## Wiring it into an AI client
 
-```bash
-apicircle-mcp --workspace /path/to/your/cloned/workspace/repo
-# or
-APICIRCLE_WORKSPACE=/path/to/cloned/workspace/repo apicircle-mcp
+<details>
+<summary><strong>Claude Desktop</strong></summary>
+
+Add to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "apicircle": {
+      "command": "apicircle-mcp"
+    }
+  }
+}
 ```
 
-The server reads JSON-RPC on stdin and writes responses on stdout. Logs go to stderr. Wire it into your AI client per [Connect your AI client](https://github.com/apicircle/studio/blob/main/docs/connect-your-ai-client.md).
+</details>
+
+<details>
+<summary><strong>Cursor / Codex / any stdio MCP client</strong></summary>
+
+Same shape — a single `command` entry pointing at the `apicircle-mcp` binary.
+Use `--workspace <path>` to scope to one workspace.
+
+</details>
+
+## How the server picks a workspace
+
+`apicircle-mcp` auto-detects the directory passed via `--workspace <dir>`
+(or `APICIRCLE_WORKSPACE`):
+
+| Contents of the directory    | Mode                                                                                                        |
+| ---------------------------- | ----------------------------------------------------------------------------------------------------------- |
+| `registry.json` present      | **Multi-workspace.** Loads the registry, binds the active workspace, exposes the rest via `workspace.list`. |
+| `workspace.synced.json` only | **Single-workspace.** Legacy boot for CI / git-cloned repos.                                                |
+| No flag at all               | Falls back to the current working directory.                                                                |
+
+In multi-workspace mode the assistant gets two extra surfaces:
+
+- **`workspace.list`** — returns every workspace + per-workspace counts
+  (requests, folders, environments, mocks, plans) + which is active. The
+  response includes a `hint` field the AI can surface to the user when
+  disambiguating between workspaces.
+- **`workspace.read` ambiguous envelope** — when called with no
+  `workspaceId` and more than one workspace exists, the response is a
+  structured `{ kind: 'multiple-workspaces', activeWorkspaceId, workspaceCount, workspaces, hint }`
+  so the AI can clarify before drilling in.
+
+```json
+{
+  "kind": "multiple-workspaces",
+  "activeWorkspaceId": "ws-a",
+  "workspaceCount": 2,
+  "workspaces": [
+    { "id": "ws-a", "name": "Petstore", "isActive": true, "counts": { "requests": 12 } },
+    { "id": "ws-b", "name": "Internal API", "isActive": false, "counts": { "requests": 47 } }
+  ],
+  "hint": "Found 2 workspaces. Re-call workspace.read with workspaceId set to the desired entry..."
+}
+```
+
+Entity tools (`request.read`, `environment.create`, `mock.start`, etc.) all
+default to the active workspace — multi-workspace scoping is opt-in per call.
+
+## The tool catalog (71 tools)
+
+The full list lives at
+[`docs/mcp-tools-reference.md`](https://github.com/apicircle/studio/blob/main/docs/mcp-tools-reference.md).
+Highlights by category:
+
+| Category                    | What the AI can do                                                                                 |
+| --------------------------- | -------------------------------------------------------------------------------------------------- |
+| **Workspaces**              | `workspace.list`, `workspace.read`, `workspace.write` (bulk + scoped by `workspaceId`)             |
+| **Entity CRUD**             | Requests, folders, environments, plans, assertions — full read / write surface                     |
+| **Imports**                 | `import.curl`, `import.openapi`, `import.postman`, `import.insomnia`, `import.har`                 |
+| **Code generation**         | `generate.code` for cURL, fetch, axios, Python requests, Go, Rust                                  |
+| **Codebase analysis**       | `codebase.extract_collection` — Express, FastAPI, NestJS, Spring                                   |
+| **Prompt-driven authoring** | LLM-shaped JSON entry points for request / folder / environment / assertion / plan / mock creation |
+| **Mock servers**            | `mock.create_from_openapi`, `mock.start`, `mock.stop`, `mock.delete`, …                            |
+| **History**                 | `history.list_runs`, `history.get_run`, `history.delete_run`, `history.purge_by_age`               |
 
-## Use programmatically
+## Embed it in your own product
+
+The host is plain TypeScript; the transport is plain stdio.
+
+### Single workspace, embedded
 
 ```ts
 import {
@@ -58,29 +168,72 @@ const host = createMcpServer({
   workspace: new FileBackedWorkspaceProvider('/path/to/workspace'),
   mock: new InProcessMockController(),
 });
-await host.connect(); // stdio by default
+await host.connect();
 ```
 
-## Tool catalog
+### Multi workspace, embedded
+
+```ts
+import {
+  createMcpServer,
+  MultiWorkspaceProvider,
+  InProcessMockController,
+} from '@apicircle/mcp-server';
 
-71 tools — see the [MCP tool catalog reference](https://github.com/apicircle/studio/blob/main/docs/mcp-tools-reference.md). Highlights:
+const workspaces = new MultiWorkspaceProvider('/path/to/workspaces-root');
+const registry = await workspaces.init();
+console.error(`Booting against ${registry.workspaces.length} workspace(s)`);
 
-- **Imports**: `import.{curl,openapi,postman,insomnia,har}`
-- **Codegen**: `generate.code` (curl, fetch, axios, requests, Go, Rust)
-- **Codebase**: `codebase.extract_collection` (Express, FastAPI, NestJS, Spring)
-- **Prompt-driven**: LLM-shaped JSON entry points covering every authoring workflow — `prompt.create_request` / `update_request`, `prompt.create_folder_tree`, `prompt.create_environment`, `prompt.create_assertion`, `prompt.create_plan` / `add_plan_steps` / `set_plan_variables`, `prompt.create_mock_server` / `add_mock_endpoint` / `set_endpoint_{validation,response}_rules` / `set_endpoint_multipliers`
-- **Mock CRUD**: `mock.{create_from_openapi,start,stop,delete,...}`
-- **Entity CRUD**: full read/write surface for requests, folders, environments, plans, assertions
+const host = createMcpServer({
+  workspace: workspaces.activeProvider(),
+  workspaces, // backs `workspace.list`
+  mock: new InProcessMockController(),
+});
+await host.connect();
+```
 
 ## Provider interfaces
 
-The host is decoupled from where state lives. Three providers ship:
+The host is decoupled from where state lives — swap providers to swap backends.
+
+| Provider                      | Use when…                                                                                   |
+| ----------------------------- | ------------------------------------------------------------------------------------------- |
+| `InMemoryWorkspaceProvider`   | Writing tests or programmatic embedding with ephemeral state.                               |
+| `FileBackedWorkspaceProvider` | CLI / headless use — advisory-locks the workspace file via `proper-lockfile`.               |
+| `MultiWorkspaceProvider`      | Registry-root-backed; implements the `Workspaces` interface that powers `workspace.list`.   |
+| `SingleWorkspaceAdapter`      | Wrap a single `WorkspaceProvider` so legacy single-dir hosts still answer `workspace.list`. |
+| `InProcessMockController`     | Runs mocks directly via `@apicircle/mock-server-core` in-process.                           |
+
+The Electron desktop app supplies its own IPC-backed providers so the
+renderer-side store stays the source of truth.
+
+## Use cases
+
+- **AI-pair-programming over your APIs.** "Add an endpoint to delete a pet,
+  generate a Go client, and write a smoke test." — done in one chat.
+- **Onboard a new dev** by handing them an MCP-enabled assistant pre-wired
+  to your team's workspace.
+- **Document drift detection.** Have the AI scan your codebase, diff against
+  the workspace, propose a PR.
+- **Spec-driven mocking.** Drop an OpenAPI file in chat; ask the AI to spin
+  up a mock; iterate on the frontend without touching the spec again.
+- **CI automation.** Use the same MCP host as a headless executor for
+  scripted, AI-authored regression suites.
+
+## Where it fits
+
+```
+@apicircle/shared              (types + MCP_TOOL_NAMES catalog)
+└── @apicircle/core            (the engine that handles each tool call)
+    └── @apicircle/mcp-server  ◀── you are here
+        └── @apicircle/cli     (re-exports as `apicircle mcp`)
+```
 
-- `InMemoryWorkspaceProvider` — for tests / programmatic embedding.
-- `FileBackedWorkspaceProvider` — for CLI / headless use; advisory-locks the workspace file via `proper-lockfile`.
-- `InProcessMockController` — runs mocks directly via `@apicircle/mock-server-core`.
+## Learn more
 
-The Electron desktop app supplies its own IPC-backed providers so renderer-side state stays consistent.
+- **Full tool catalog**: <https://github.com/apicircle/studio/blob/main/docs/mcp-tools-reference.md>
+- **Connect your AI client**: <https://github.com/apicircle/studio/blob/main/docs/connect-your-ai-client.md>
+- **Platform architecture**: <https://github.com/apicircle/studio/blob/main/docs/architecture/platform.md>
 
 ## License