@apicircle/mcp-server 1.0.1 → 1.0.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +110 -110
- package/README.md +191 -38
- package/dist/bin/mcp-server.cjs +606 -352
- package/dist/bin/mcp-server.cjs.map +1 -1
- package/dist/index.cjs +577 -350
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +88 -1
- package/dist/index.d.ts +88 -1
- package/dist/index.js +580 -350
- package/dist/index.js.map +1 -1
- package/package.json +33 -26
package/LICENSE
CHANGED
|
@@ -1,110 +1,110 @@
|
|
|
1
|
-
API Circle Studio License
|
|
2
|
-
Custom Source-Available License, v1.0
|
|
3
|
-
|
|
4
|
-
Copyright (c) 2026 Deva Prakash ("Licensor")
|
|
5
|
-
|
|
6
|
-
The source code in this repository ("the Software") is made available for
|
|
7
|
-
the purposes of transparency, security review, contribution, and personal
|
|
8
|
-
evaluation. This is NOT an open-source license as defined by the Open
|
|
9
|
-
Source Initiative.
|
|
10
|
-
|
|
11
|
-
0. Definitions
|
|
12
|
-
|
|
13
|
-
"Commercial Use" means any use of the Software that is intended for
|
|
14
|
-
or directed toward commercial advantage or monetary compensation,
|
|
15
|
-
whether direct or indirect, including without limitation:
|
|
16
|
-
|
|
17
|
-
(a) using the Software to build, test, develop, deploy, or operate
|
|
18
|
-
any product, service, application, or system that is sold,
|
|
19
|
-
licensed, hosted, distributed, or otherwise made available to
|
|
20
|
-
any third party for a fee or other consideration;
|
|
21
|
-
(b) using the Software in the course of paid employment, paid
|
|
22
|
-
consulting, paid contracting, freelance work, or any other
|
|
23
|
-
revenue-generating activity, regardless of whether the Software
|
|
24
|
-
itself is sold or transferred;
|
|
25
|
-
(c) using the Software internally within a for-profit organization
|
|
26
|
-
beyond the Evaluation Period defined below;
|
|
27
|
-
(d) integrating the Software, or any portion of it, into any tool,
|
|
28
|
-
pipeline, automation, or workflow that supports the commercial
|
|
29
|
-
operations of any business;
|
|
30
|
-
(e) using the Software to provide a hosted, managed, or embedded
|
|
31
|
-
service of any kind to a third party, whether free or paid.
|
|
32
|
-
|
|
33
|
-
"Non-Commercial Use" means any use that is not Commercial Use,
|
|
34
|
-
including personal hobby projects, individual learning, academic
|
|
35
|
-
research, classroom instruction, and good-faith contribution to
|
|
36
|
-
this repository.
|
|
37
|
-
|
|
38
|
-
"Evaluation Period" means a single, continuous period of up to
|
|
39
|
-
thirty (30) days during which a for-profit organization may
|
|
40
|
-
internally evaluate the Software at no charge. After the Evaluation
|
|
41
|
-
Period expires, any further use of the Software by that organization
|
|
42
|
-
constitutes Commercial Use and requires a separate commercial
|
|
43
|
-
license from the Licensor.
|
|
44
|
-
|
|
45
|
-
1. Permitted Use
|
|
46
|
-
|
|
47
|
-
You may, without charge:
|
|
48
|
-
|
|
49
|
-
(a) view, read, and study the source code of the Software;
|
|
50
|
-
(b) run the Software, in source or compiled form, for your own
|
|
51
|
-
Non-Commercial Use, or for Commercial Use solely within the
|
|
52
|
-
Evaluation Period;
|
|
53
|
-
(c) submit improvements to the Software back to this repository via
|
|
54
|
-
pull request, subject to Section 3 (Contributions).
|
|
55
|
-
|
|
56
|
-
2. Prohibited Use
|
|
57
|
-
|
|
58
|
-
Without prior written permission from the Licensor, you may NOT:
|
|
59
|
-
|
|
60
|
-
(a) make any Commercial Use of the Software, in whole or in part,
|
|
61
|
-
except during the Evaluation Period as defined in Section 0;
|
|
62
|
-
(b) redistribute the Software, in source or compiled form, whether
|
|
63
|
-
modified or unmodified, to any third party;
|
|
64
|
-
(c) sublicense, sell, rent, lease, or otherwise transfer the
|
|
65
|
-
Software or any rights granted herein;
|
|
66
|
-
(d) remove, obscure, or alter any copyright, trademark, attribution,
|
|
67
|
-
or license notice contained in the Software;
|
|
68
|
-
(e) use the names "API Circle", "API Circle Studio", or any related
|
|
69
|
-
logos or trademarks, except as required for accurate attribution.
|
|
70
|
-
|
|
71
|
-
3. Contributions
|
|
72
|
-
|
|
73
|
-
By submitting any contribution (including but not limited to code,
|
|
74
|
-
documentation, or assets) to this repository, you grant the Licensor
|
|
75
|
-
a perpetual, worldwide, irrevocable, royalty-free, sublicensable
|
|
76
|
-
license to use, modify, distribute, and relicense your contribution
|
|
77
|
-
under any terms, including the terms of this license or any future
|
|
78
|
-
version thereof.
|
|
79
|
-
|
|
80
|
-
4. No Trademark License
|
|
81
|
-
|
|
82
|
-
This license does not grant permission to use the trade names,
|
|
83
|
-
trademarks, service marks, or product names of the Licensor, except
|
|
84
|
-
as required for reasonable and customary use in describing the
|
|
85
|
-
origin of the Software.
|
|
86
|
-
|
|
87
|
-
5. Termination
|
|
88
|
-
|
|
89
|
-
The rights granted in Section 1 terminate automatically if you
|
|
90
|
-
breach any term of this license. Upon termination, you must cease
|
|
91
|
-
all use of the Software and destroy all copies in your possession.
|
|
92
|
-
|
|
93
|
-
6. Disclaimer of Warranty
|
|
94
|
-
|
|
95
|
-
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
|
|
96
|
-
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
|
|
97
|
-
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, TITLE, AND
|
|
98
|
-
NON-INFRINGEMENT.
|
|
99
|
-
|
|
100
|
-
7. Limitation of Liability
|
|
101
|
-
|
|
102
|
-
IN NO EVENT SHALL THE LICENSOR BE LIABLE FOR ANY CLAIM, DAMAGES, OR
|
|
103
|
-
OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT, OR
|
|
104
|
-
OTHERWISE, ARISING FROM, OUT OF, OR IN CONNECTION WITH THE SOFTWARE
|
|
105
|
-
OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|
|
106
|
-
|
|
107
|
-
8. Commercial Licensing
|
|
108
|
-
|
|
109
|
-
For commercial licensing, redistribution, or any use not permitted
|
|
110
|
-
under Section 1, contact: apicircle365@gmail.com
|
|
1
|
+
API Circle Studio License
|
|
2
|
+
Custom Source-Available License, v1.0
|
|
3
|
+
|
|
4
|
+
Copyright (c) 2026 Deva Prakash ("Licensor")
|
|
5
|
+
|
|
6
|
+
The source code in this repository ("the Software") is made available for
|
|
7
|
+
the purposes of transparency, security review, contribution, and personal
|
|
8
|
+
evaluation. This is NOT an open-source license as defined by the Open
|
|
9
|
+
Source Initiative.
|
|
10
|
+
|
|
11
|
+
0. Definitions
|
|
12
|
+
|
|
13
|
+
"Commercial Use" means any use of the Software that is intended for
|
|
14
|
+
or directed toward commercial advantage or monetary compensation,
|
|
15
|
+
whether direct or indirect, including without limitation:
|
|
16
|
+
|
|
17
|
+
(a) using the Software to build, test, develop, deploy, or operate
|
|
18
|
+
any product, service, application, or system that is sold,
|
|
19
|
+
licensed, hosted, distributed, or otherwise made available to
|
|
20
|
+
any third party for a fee or other consideration;
|
|
21
|
+
(b) using the Software in the course of paid employment, paid
|
|
22
|
+
consulting, paid contracting, freelance work, or any other
|
|
23
|
+
revenue-generating activity, regardless of whether the Software
|
|
24
|
+
itself is sold or transferred;
|
|
25
|
+
(c) using the Software internally within a for-profit organization
|
|
26
|
+
beyond the Evaluation Period defined below;
|
|
27
|
+
(d) integrating the Software, or any portion of it, into any tool,
|
|
28
|
+
pipeline, automation, or workflow that supports the commercial
|
|
29
|
+
operations of any business;
|
|
30
|
+
(e) using the Software to provide a hosted, managed, or embedded
|
|
31
|
+
service of any kind to a third party, whether free or paid.
|
|
32
|
+
|
|
33
|
+
"Non-Commercial Use" means any use that is not Commercial Use,
|
|
34
|
+
including personal hobby projects, individual learning, academic
|
|
35
|
+
research, classroom instruction, and good-faith contribution to
|
|
36
|
+
this repository.
|
|
37
|
+
|
|
38
|
+
"Evaluation Period" means a single, continuous period of up to
|
|
39
|
+
thirty (30) days during which a for-profit organization may
|
|
40
|
+
internally evaluate the Software at no charge. After the Evaluation
|
|
41
|
+
Period expires, any further use of the Software by that organization
|
|
42
|
+
constitutes Commercial Use and requires a separate commercial
|
|
43
|
+
license from the Licensor.
|
|
44
|
+
|
|
45
|
+
1. Permitted Use
|
|
46
|
+
|
|
47
|
+
You may, without charge:
|
|
48
|
+
|
|
49
|
+
(a) view, read, and study the source code of the Software;
|
|
50
|
+
(b) run the Software, in source or compiled form, for your own
|
|
51
|
+
Non-Commercial Use, or for Commercial Use solely within the
|
|
52
|
+
Evaluation Period;
|
|
53
|
+
(c) submit improvements to the Software back to this repository via
|
|
54
|
+
pull request, subject to Section 3 (Contributions).
|
|
55
|
+
|
|
56
|
+
2. Prohibited Use
|
|
57
|
+
|
|
58
|
+
Without prior written permission from the Licensor, you may NOT:
|
|
59
|
+
|
|
60
|
+
(a) make any Commercial Use of the Software, in whole or in part,
|
|
61
|
+
except during the Evaluation Period as defined in Section 0;
|
|
62
|
+
(b) redistribute the Software, in source or compiled form, whether
|
|
63
|
+
modified or unmodified, to any third party;
|
|
64
|
+
(c) sublicense, sell, rent, lease, or otherwise transfer the
|
|
65
|
+
Software or any rights granted herein;
|
|
66
|
+
(d) remove, obscure, or alter any copyright, trademark, attribution,
|
|
67
|
+
or license notice contained in the Software;
|
|
68
|
+
(e) use the names "API Circle", "API Circle Studio", or any related
|
|
69
|
+
logos or trademarks, except as required for accurate attribution.
|
|
70
|
+
|
|
71
|
+
3. Contributions
|
|
72
|
+
|
|
73
|
+
By submitting any contribution (including but not limited to code,
|
|
74
|
+
documentation, or assets) to this repository, you grant the Licensor
|
|
75
|
+
a perpetual, worldwide, irrevocable, royalty-free, sublicensable
|
|
76
|
+
license to use, modify, distribute, and relicense your contribution
|
|
77
|
+
under any terms, including the terms of this license or any future
|
|
78
|
+
version thereof.
|
|
79
|
+
|
|
80
|
+
4. No Trademark License
|
|
81
|
+
|
|
82
|
+
This license does not grant permission to use the trade names,
|
|
83
|
+
trademarks, service marks, or product names of the Licensor, except
|
|
84
|
+
as required for reasonable and customary use in describing the
|
|
85
|
+
origin of the Software.
|
|
86
|
+
|
|
87
|
+
5. Termination
|
|
88
|
+
|
|
89
|
+
The rights granted in Section 1 terminate automatically if you
|
|
90
|
+
breach any term of this license. Upon termination, you must cease
|
|
91
|
+
all use of the Software and destroy all copies in your possession.
|
|
92
|
+
|
|
93
|
+
6. Disclaimer of Warranty
|
|
94
|
+
|
|
95
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
|
|
96
|
+
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
|
|
97
|
+
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, TITLE, AND
|
|
98
|
+
NON-INFRINGEMENT.
|
|
99
|
+
|
|
100
|
+
7. Limitation of Liability
|
|
101
|
+
|
|
102
|
+
IN NO EVENT SHALL THE LICENSOR BE LIABLE FOR ANY CLAIM, DAMAGES, OR
|
|
103
|
+
OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT, OR
|
|
104
|
+
OTHERWISE, ARISING FROM, OUT OF, OR IN CONNECTION WITH THE SOFTWARE
|
|
105
|
+
OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|
|
106
|
+
|
|
107
|
+
8. Commercial Licensing
|
|
108
|
+
|
|
109
|
+
For commercial licensing, redistribution, or any use not permitted
|
|
110
|
+
under Section 1, contact: apicircle365@gmail.com
|
package/README.md
CHANGED
|
@@ -4,48 +4,158 @@
|
|
|
4
4
|
|
|
5
5
|
<h1 align="center">@apicircle/mcp-server</h1>
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
<p align="center">
|
|
8
|
+
<strong>Give your AI assistant a real API client.</strong><br />
|
|
9
|
+
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.
|
|
10
|
+
</p>
|
|
11
|
+
|
|
12
|
+
<p align="center">
|
|
13
|
+
<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>
|
|
14
|
+
<img src="https://img.shields.io/badge/MCP%20tools-71-blueviolet" alt="71 MCP tools" />
|
|
15
|
+
<img src="https://img.shields.io/badge/transport-stdio-blue" alt="stdio transport" />
|
|
16
|
+
<img src="https://img.shields.io/badge/multi--workspace-yes-success" alt="Multi-workspace" />
|
|
17
|
+
<img src="https://img.shields.io/badge/node-%E2%89%A5%2020-brightgreen" alt="Node ≥ 20" />
|
|
18
|
+
</p>
|
|
19
|
+
|
|
20
|
+
---
|
|
21
|
+
|
|
22
|
+
## What this gives your AI
|
|
23
|
+
|
|
24
|
+
Most "AI + API client" integrations stop at autocompletion. This goes much
|
|
25
|
+
further. When you wire `@apicircle/mcp-server` into Claude Desktop, Claude
|
|
26
|
+
Code, ChatGPT, Cursor, Codex, Copilot, Continue, Cline, Zed, Windsurf — any
|
|
27
|
+
MCP-compatible client — your assistant gains the ability to:
|
|
28
|
+
|
|
29
|
+
- **Read your workspace.** Browse requests, folders, environments, plans,
|
|
30
|
+
and mock servers across **multiple workspaces** on the same machine.
|
|
31
|
+
- **Author requests.** Create, rename, move, and delete requests / folders /
|
|
32
|
+
environments / assertions with prompt-driven, LLM-shaped JSON tools.
|
|
33
|
+
- **Import specs.** Drop in an OpenAPI / Swagger / Postman / Insomnia / HAR /
|
|
34
|
+
cURL file and the assistant turns it into a typed collection.
|
|
35
|
+
- **Generate code.** Emit working clients in **cURL, fetch, axios, Python
|
|
36
|
+
requests, Go, and Rust** for any request.
|
|
37
|
+
- **Extract from your codebase.** Scan an Express, FastAPI, NestJS, or
|
|
38
|
+
Spring project and propose a request collection that mirrors the routes.
|
|
39
|
+
- **Mock APIs.** Boot a real local mock server from an OpenAPI spec —
|
|
40
|
+
start, stop, and tear down — straight from the chat.
|
|
41
|
+
- **Run + replay history.** List history runs, replay them, purge old ones.
|
|
42
|
+
|
|
43
|
+
All without you leaving the conversation.
|
|
8
44
|
|
|
9
45
|
## Install
|
|
10
46
|
|
|
11
47
|
```bash
|
|
12
|
-
#
|
|
48
|
+
# The common case — install globally and wire as a stdio MCP server
|
|
13
49
|
npm install -g @apicircle/mcp-server
|
|
14
50
|
|
|
15
|
-
# Or as a
|
|
51
|
+
# Or as a library, when you're embedding the host in your own product
|
|
16
52
|
npm install @apicircle/mcp-server
|
|
17
53
|
```
|
|
18
54
|
|
|
19
|
-
##
|
|
20
|
-
|
|
21
|
-
`--workspace <dir>` points the server at a directory containing
|
|
22
|
-
`workspace.synced.json` + `workspace.local.json`. **That directory is a
|
|
23
|
-
git-cloned API Circle workspace repo** — created by the Desktop app's
|
|
24
|
-
_Link to Git_ feature, then cloned with `git clone`:
|
|
55
|
+
## Quick start
|
|
25
56
|
|
|
26
57
|
```bash
|
|
27
|
-
|
|
28
|
-
apicircle-mcp
|
|
58
|
+
# Multi-workspace mode (default) — exposes every workspace on this machine
|
|
59
|
+
apicircle-mcp
|
|
60
|
+
|
|
61
|
+
# Single-workspace mode — point at a folder with a workspace.synced.json
|
|
62
|
+
# (CI, a git-cloned workspace repo, etc.)
|
|
63
|
+
apicircle-mcp --workspace /path/to/checkout-repo
|
|
29
64
|
```
|
|
30
65
|
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
when you've outgrown the in-app flow.
|
|
66
|
+
The server speaks JSON-RPC on stdin/stdout (logs to stderr). Plug it into
|
|
67
|
+
your AI client per the
|
|
68
|
+
[Connect your AI client](https://github.com/apicircle/studio/blob/main/docs/connect-your-ai-client.md)
|
|
69
|
+
guide, or copy/paste the snippet generated by the desktop app's
|
|
70
|
+
**MCP → How to Connect** panel.
|
|
37
71
|
|
|
38
|
-
##
|
|
72
|
+
## Wiring it into an AI client
|
|
39
73
|
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
74
|
+
<details>
|
|
75
|
+
<summary><strong>Claude Desktop</strong></summary>
|
|
76
|
+
|
|
77
|
+
Add to `claude_desktop_config.json`:
|
|
78
|
+
|
|
79
|
+
```json
|
|
80
|
+
{
|
|
81
|
+
"mcpServers": {
|
|
82
|
+
"apicircle": {
|
|
83
|
+
"command": "apicircle-mcp"
|
|
84
|
+
}
|
|
85
|
+
}
|
|
86
|
+
}
|
|
44
87
|
```
|
|
45
88
|
|
|
46
|
-
|
|
89
|
+
</details>
|
|
90
|
+
|
|
91
|
+
<details>
|
|
92
|
+
<summary><strong>Cursor / Codex / any stdio MCP client</strong></summary>
|
|
93
|
+
|
|
94
|
+
Same shape — a single `command` entry pointing at the `apicircle-mcp` binary.
|
|
95
|
+
Use `--workspace <path>` to scope to one workspace.
|
|
96
|
+
|
|
97
|
+
</details>
|
|
98
|
+
|
|
99
|
+
## How the server picks a workspace
|
|
100
|
+
|
|
101
|
+
`apicircle-mcp` auto-detects the directory passed via `--workspace <dir>`
|
|
102
|
+
(or `APICIRCLE_WORKSPACE`):
|
|
103
|
+
|
|
104
|
+
| Contents of the directory | Mode |
|
|
105
|
+
| ---------------------------- | ----------------------------------------------------------------------------------------------------------- |
|
|
106
|
+
| `registry.json` present | **Multi-workspace.** Loads the registry, binds the active workspace, exposes the rest via `workspace.list`. |
|
|
107
|
+
| `workspace.synced.json` only | **Single-workspace.** Legacy boot for CI / git-cloned repos. |
|
|
108
|
+
| No flag at all | Falls back to the current working directory. |
|
|
109
|
+
|
|
110
|
+
In multi-workspace mode the assistant gets two extra surfaces:
|
|
111
|
+
|
|
112
|
+
- **`workspace.list`** — returns every workspace + per-workspace counts
|
|
113
|
+
(requests, folders, environments, mocks, plans) + which is active. The
|
|
114
|
+
response includes a `hint` field the AI can surface to the user when
|
|
115
|
+
disambiguating between workspaces.
|
|
116
|
+
- **`workspace.read` ambiguous envelope** — when called with no
|
|
117
|
+
`workspaceId` and more than one workspace exists, the response is a
|
|
118
|
+
structured `{ kind: 'multiple-workspaces', activeWorkspaceId, workspaceCount, workspaces, hint }`
|
|
119
|
+
so the AI can clarify before drilling in.
|
|
120
|
+
|
|
121
|
+
```json
|
|
122
|
+
{
|
|
123
|
+
"kind": "multiple-workspaces",
|
|
124
|
+
"activeWorkspaceId": "ws-a",
|
|
125
|
+
"workspaceCount": 2,
|
|
126
|
+
"workspaces": [
|
|
127
|
+
{ "id": "ws-a", "name": "Petstore", "isActive": true, "counts": { "requests": 12 } },
|
|
128
|
+
{ "id": "ws-b", "name": "Internal API", "isActive": false, "counts": { "requests": 47 } }
|
|
129
|
+
],
|
|
130
|
+
"hint": "Found 2 workspaces. Re-call workspace.read with workspaceId set to the desired entry..."
|
|
131
|
+
}
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
Entity tools (`request.read`, `environment.create`, `mock.start`, etc.) all
|
|
135
|
+
default to the active workspace — multi-workspace scoping is opt-in per call.
|
|
136
|
+
|
|
137
|
+
## The tool catalog (71 tools)
|
|
138
|
+
|
|
139
|
+
The full list lives at
|
|
140
|
+
[`docs/mcp-tools-reference.md`](https://github.com/apicircle/studio/blob/main/docs/mcp-tools-reference.md).
|
|
141
|
+
Highlights by category:
|
|
142
|
+
|
|
143
|
+
| Category | What the AI can do |
|
|
144
|
+
| --------------------------- | -------------------------------------------------------------------------------------------------- |
|
|
145
|
+
| **Workspaces** | `workspace.list`, `workspace.read`, `workspace.write` (bulk + scoped by `workspaceId`) |
|
|
146
|
+
| **Entity CRUD** | Requests, folders, environments, plans, assertions — full read / write surface |
|
|
147
|
+
| **Imports** | `import.curl`, `import.openapi`, `import.postman`, `import.insomnia`, `import.har` |
|
|
148
|
+
| **Code generation** | `generate.code` for cURL, fetch, axios, Python requests, Go, Rust |
|
|
149
|
+
| **Codebase analysis** | `codebase.extract_collection` — Express, FastAPI, NestJS, Spring |
|
|
150
|
+
| **Prompt-driven authoring** | LLM-shaped JSON entry points for request / folder / environment / assertion / plan / mock creation |
|
|
151
|
+
| **Mock servers** | `mock.create_from_openapi`, `mock.start`, `mock.stop`, `mock.delete`, … |
|
|
152
|
+
| **History** | `history.list_runs`, `history.get_run`, `history.delete_run`, `history.purge_by_age` |
|
|
47
153
|
|
|
48
|
-
##
|
|
154
|
+
## Embed it in your own product
|
|
155
|
+
|
|
156
|
+
The host is plain TypeScript; the transport is plain stdio.
|
|
157
|
+
|
|
158
|
+
### Single workspace, embedded
|
|
49
159
|
|
|
50
160
|
```ts
|
|
51
161
|
import {
|
|
@@ -58,29 +168,72 @@ const host = createMcpServer({
|
|
|
58
168
|
workspace: new FileBackedWorkspaceProvider('/path/to/workspace'),
|
|
59
169
|
mock: new InProcessMockController(),
|
|
60
170
|
});
|
|
61
|
-
await host.connect();
|
|
171
|
+
await host.connect();
|
|
62
172
|
```
|
|
63
173
|
|
|
64
|
-
|
|
174
|
+
### Multi workspace, embedded
|
|
175
|
+
|
|
176
|
+
```ts
|
|
177
|
+
import {
|
|
178
|
+
createMcpServer,
|
|
179
|
+
MultiWorkspaceProvider,
|
|
180
|
+
InProcessMockController,
|
|
181
|
+
} from '@apicircle/mcp-server';
|
|
65
182
|
|
|
66
|
-
|
|
183
|
+
const workspaces = new MultiWorkspaceProvider('/path/to/workspaces-root');
|
|
184
|
+
const registry = await workspaces.init();
|
|
185
|
+
console.error(`Booting against ${registry.workspaces.length} workspace(s)`);
|
|
67
186
|
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
187
|
+
const host = createMcpServer({
|
|
188
|
+
workspace: workspaces.activeProvider(),
|
|
189
|
+
workspaces, // backs `workspace.list`
|
|
190
|
+
mock: new InProcessMockController(),
|
|
191
|
+
});
|
|
192
|
+
await host.connect();
|
|
193
|
+
```
|
|
74
194
|
|
|
75
195
|
## Provider interfaces
|
|
76
196
|
|
|
77
|
-
The host is decoupled from where state lives
|
|
197
|
+
The host is decoupled from where state lives — swap providers to swap backends.
|
|
198
|
+
|
|
199
|
+
| Provider | Use when… |
|
|
200
|
+
| ----------------------------- | ------------------------------------------------------------------------------------------- |
|
|
201
|
+
| `InMemoryWorkspaceProvider` | Writing tests or programmatic embedding with ephemeral state. |
|
|
202
|
+
| `FileBackedWorkspaceProvider` | CLI / headless use — advisory-locks the workspace file via `proper-lockfile`. |
|
|
203
|
+
| `MultiWorkspaceProvider` | Registry-root-backed; implements the `Workspaces` interface that powers `workspace.list`. |
|
|
204
|
+
| `SingleWorkspaceAdapter` | Wrap a single `WorkspaceProvider` so legacy single-dir hosts still answer `workspace.list`. |
|
|
205
|
+
| `InProcessMockController` | Runs mocks directly via `@apicircle/mock-server-core` in-process. |
|
|
206
|
+
|
|
207
|
+
The Electron desktop app supplies its own IPC-backed providers so the
|
|
208
|
+
renderer-side store stays the source of truth.
|
|
209
|
+
|
|
210
|
+
## Use cases
|
|
211
|
+
|
|
212
|
+
- **AI-pair-programming over your APIs.** "Add an endpoint to delete a pet,
|
|
213
|
+
generate a Go client, and write a smoke test." — done in one chat.
|
|
214
|
+
- **Onboard a new dev** by handing them an MCP-enabled assistant pre-wired
|
|
215
|
+
to your team's workspace.
|
|
216
|
+
- **Document drift detection.** Have the AI scan your codebase, diff against
|
|
217
|
+
the workspace, propose a PR.
|
|
218
|
+
- **Spec-driven mocking.** Drop an OpenAPI file in chat; ask the AI to spin
|
|
219
|
+
up a mock; iterate on the frontend without touching the spec again.
|
|
220
|
+
- **CI automation.** Use the same MCP host as a headless executor for
|
|
221
|
+
scripted, AI-authored regression suites.
|
|
222
|
+
|
|
223
|
+
## Where it fits
|
|
224
|
+
|
|
225
|
+
```
|
|
226
|
+
@apicircle/shared (types + MCP_TOOL_NAMES catalog)
|
|
227
|
+
└── @apicircle/core (the engine that handles each tool call)
|
|
228
|
+
└── @apicircle/mcp-server ◀── you are here
|
|
229
|
+
└── @apicircle/cli (re-exports as `apicircle mcp`)
|
|
230
|
+
```
|
|
78
231
|
|
|
79
|
-
|
|
80
|
-
- `FileBackedWorkspaceProvider` — for CLI / headless use; advisory-locks the workspace file via `proper-lockfile`.
|
|
81
|
-
- `InProcessMockController` — runs mocks directly via `@apicircle/mock-server-core`.
|
|
232
|
+
## Learn more
|
|
82
233
|
|
|
83
|
-
|
|
234
|
+
- **Full tool catalog**: <https://github.com/apicircle/studio/blob/main/docs/mcp-tools-reference.md>
|
|
235
|
+
- **Connect your AI client**: <https://github.com/apicircle/studio/blob/main/docs/connect-your-ai-client.md>
|
|
236
|
+
- **Platform architecture**: <https://github.com/apicircle/studio/blob/main/docs/architecture/platform.md>
|
|
84
237
|
|
|
85
238
|
## License
|
|
86
239
|
|