plugmcp 0.0.0-stage → 0.1.0
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 +21 -0
- package/README.md +232 -2
- package/dist/agent.d.ts +20 -0
- package/dist/agent.js +35 -0
- package/dist/build.d.ts +13 -0
- package/dist/build.js +83 -0
- package/dist/cli/cloud.d.ts +20 -0
- package/dist/cli/cloud.js +56 -0
- package/dist/cli/index.d.ts +2 -0
- package/dist/cli/index.js +326 -0
- package/dist/dev/api.d.ts +37 -0
- package/dist/dev/api.js +788 -0
- package/dist/dev/chat.d.ts +63 -0
- package/dist/dev/chat.js +159 -0
- package/dist/dev/dev.d.ts +22 -0
- package/dist/dev/dev.js +188 -0
- package/dist/dev/edit.d.ts +22 -0
- package/dist/dev/edit.js +147 -0
- package/dist/dev/generate.d.ts +21 -0
- package/dist/dev/generate.js +97 -0
- package/dist/dev/keys.d.ts +61 -0
- package/dist/dev/keys.js +55 -0
- package/dist/dev/project.d.ts +26 -0
- package/dist/dev/project.js +68 -0
- package/dist/dev/store.d.ts +61 -0
- package/dist/dev/store.js +113 -0
- package/dist/dev/views.d.ts +9 -0
- package/dist/dev/views.js +54 -0
- package/dist/http.d.ts +33 -0
- package/dist/http.js +79 -0
- package/dist/index.d.ts +77 -0
- package/dist/index.js +118 -0
- package/dist/install.d.ts +13 -0
- package/dist/install.js +54 -0
- package/dist/landing.d.ts +3 -0
- package/dist/landing.js +62 -0
- package/dist/stdio.d.ts +3 -0
- package/dist/stdio.js +5 -0
- package/dist/view/index.d.ts +34 -0
- package/dist/view/index.js +90 -0
- package/package.json +114 -4
- package/studio-dist/assets/geist-cyrillic-ext-wght-normal-DjL33-gN.woff2 +0 -0
- package/studio-dist/assets/geist-cyrillic-wght-normal-BEAKL7Jp.woff2 +0 -0
- package/studio-dist/assets/geist-latin-ext-wght-normal-DC-KSUi6.woff2 +0 -0
- package/studio-dist/assets/geist-latin-wght-normal-BgDaEnEv.woff2 +0 -0
- package/studio-dist/assets/geist-mono-cyrillic-ext-wght-normal-X_5orZeX.woff2 +0 -0
- package/studio-dist/assets/geist-mono-cyrillic-wght-normal-DiZS0aHC.woff2 +0 -0
- package/studio-dist/assets/geist-mono-latin-ext-wght-normal-Bwz-egvJ.woff2 +0 -0
- package/studio-dist/assets/geist-mono-latin-wght-normal-XN7g48iV.woff2 +0 -0
- package/studio-dist/assets/geist-mono-symbols2-wght-normal-CO5SzqOn.woff2 +0 -0
- package/studio-dist/assets/geist-mono-vietnamese-wght-normal-DadHysG0.woff2 +0 -0
- package/studio-dist/assets/geist-vietnamese-wght-normal-6IgcOCM7.woff2 +0 -0
- package/studio-dist/assets/index-BSR7LH_V.css +1 -0
- package/studio-dist/assets/index-D_yIYje_.js +137 -0
- package/studio-dist/index.html +15 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 PlugMCP
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,233 @@
|
|
|
1
|
-
#
|
|
1
|
+
# PlugMCP: the framework for building MCP servers and MCP apps
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
**Build, test and ship MCP servers and MCP apps in TypeScript. Write a tool or ask the built-in chat to write it, see every server and tool on a canvas, edit schemas in place, save tests, and chat with your own model key. Open source, local, no account.**
|
|
4
|
+
|
|
5
|
+
[](https://www.npmjs.com/package/plugmcp)
|
|
6
|
+
[](LICENSE)
|
|
7
|
+
[](https://plugmcp.ai/mcp)
|
|
8
|
+
|
|
9
|
+
[Website](https://plugmcp.ai) · [MCP directory](https://plugmcp.ai/mcp) · [Host a server](https://plugmcp.ai/app) · [How it is built](docs/ARCHITECTURE.md)
|
|
10
|
+
|
|
11
|
+
PlugMCP is an open-source TypeScript framework for the [Model Context Protocol](https://modelcontextprotocol.io) (MCP), made by the team behind [plugmcp.ai](https://plugmcp.ai), the directory of 95,000+ MCP servers.
|
|
12
|
+
|
|
13
|
+
- An **MCP server** is a named set of tools behind one address. Any MCP client can use it: Claude, ChatGPT, Cursor, VS Code, your own agent.
|
|
14
|
+
- A **tool** is one function a model can call. You write it with [Zod](https://zod.dev) and a handler.
|
|
15
|
+
- An **MCP app** is a tool with a view: a React file that draws the tool's result inside the chat ([MCP Apps](https://modelcontextprotocol.io/extensions/apps)). Servers and apps are built the same way; an app just adds one file.
|
|
16
|
+
|
|
17
|
+
```bash
|
|
18
|
+
npx create-plugmcp my-server
|
|
19
|
+
cd my-server
|
|
20
|
+
npm run dev
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+

|
|
24
|
+
|
|
25
|
+
## How it works
|
|
26
|
+
|
|
27
|
+
1. **Create a project.** `npx create-plugmcp my-server` gives you one MCP server with a working tool and a view.
|
|
28
|
+
2. **Open the Studio.** `npm run dev` runs your servers and opens the Studio at `http://localhost:3333`.
|
|
29
|
+
3. **Add your model key.** Open **Chat**, pick a provider (OpenAI, Anthropic, Google, OpenRouter, Ollama or any OpenAI-compatible endpoint) and paste your key. It is saved on your machine and sent only to that provider.
|
|
30
|
+
4. **Build.** Ask the chat for a tool or an MCP app and it writes the code into your project and runs it. Or press **New tool**, or write `server.tool(...)` yourself.
|
|
31
|
+
5. **See it and change it.** The **Canvas** draws the MCP server with its tools under it. Click the server to edit its name and description. Click a tool for its schema, with an Edit link on every description, a form to run it, and its code.
|
|
32
|
+
6. **Test it.** Run a tool with real input and press **Save as test**. The **Tests** page runs every saved test, and `plugmcp test` does the same in a terminal or in CI.
|
|
33
|
+
7. **Connect and ship.** **Connect** gives install buttons for Cursor, VS Code, Claude Code and Codex. `plugmcp build` makes a plain Node server you can host anywhere, and [plugmcp.ai](https://plugmcp.ai) lists and hosts it.
|
|
34
|
+
|
|
35
|
+

|
|
36
|
+
|
|
37
|
+
## Why PlugMCP
|
|
38
|
+
|
|
39
|
+
- **One file per server, one file per view.** No decorators, no second project, no registration step. A file at `views/get_weather.tsx` is the UI for the tool named `get_weather`.
|
|
40
|
+
- **Several MCP servers in one project.** Start another from the Studio. Each has its own tools, its own canvas and its own address.
|
|
41
|
+
- **A chat that builds.** Say what you want. Your own model writes the tool and its view into your project, runs it and shows the result. Code that does not load is never kept.
|
|
42
|
+
- **A canvas for every server.** The server on top, its tools under it, each with its description and inputs. Drag the cards where you want them.
|
|
43
|
+
- **Schema first, editable in place.** Every tool opens on what a model sees: each input, its type, whether it is required and what it means. Change any description, or the server's own name and description, without opening the code. A form to run the tool sits beside it.
|
|
44
|
+
- **Tests you keep.** Save any run as a test, say what the result must contain, and run them all after every change, in the Studio or with `plugmcp test` in CI.
|
|
45
|
+
- **Your own key, kept local.** The key stays in a local file and goes only to the provider you chose. It never reaches the browser or us. No telemetry.
|
|
46
|
+
- **A directory built in.** Try popular servers from [plugmcp.ai](https://plugmcp.ai/mcp) next to your own, and search 95,000+ before you build a duplicate.
|
|
47
|
+
- **Works in agents.** The same tools run in-process in the Claude Agent SDK with one line, and over HTTP or stdio in anything else.
|
|
48
|
+
- **Fast.** One process. The starter is ready in about 0.2 seconds, and edits reload without a restart.
|
|
49
|
+
|
|
50
|
+
## A server
|
|
51
|
+
|
|
52
|
+
```ts
|
|
53
|
+
// server.ts
|
|
54
|
+
import { createServer } from "plugmcp";
|
|
55
|
+
import { z } from "zod";
|
|
56
|
+
|
|
57
|
+
const server = createServer({ name: "weather" });
|
|
58
|
+
|
|
59
|
+
server.tool(
|
|
60
|
+
{
|
|
61
|
+
name: "get_weather",
|
|
62
|
+
description: "Current weather for a city. Shows a weather card.",
|
|
63
|
+
input: z.object({ city: z.string().describe("City name") }),
|
|
64
|
+
},
|
|
65
|
+
async ({ city }) => {
|
|
66
|
+
const data = await lookUp(city);
|
|
67
|
+
return { city, tempC: data.temp, sky: data.sky }; // a plain object is enough
|
|
68
|
+
},
|
|
69
|
+
);
|
|
70
|
+
|
|
71
|
+
export default server;
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
The handler's input is typed from the schema. Return a string, a plain object, or a full MCP result. A thrown `Error` becomes an error result the model can read.
|
|
75
|
+
|
|
76
|
+
## A view (an MCP App)
|
|
77
|
+
|
|
78
|
+
```tsx
|
|
79
|
+
// views/get_weather.tsx
|
|
80
|
+
import { useTool } from "plugmcp/view";
|
|
81
|
+
|
|
82
|
+
export default function WeatherCard() {
|
|
83
|
+
const { output, isPending, callTool, sendMessage, theme } = useTool<{ city: string; tempC: number; sky: string }>();
|
|
84
|
+
if (isPending) return <p>Checking the weather</p>;
|
|
85
|
+
return (
|
|
86
|
+
<div>
|
|
87
|
+
<h2>{output?.tempC}° in {output?.city}</h2>
|
|
88
|
+
<button onClick={() => sendMessage(`What should I wear in ${output?.city}?`)}>Ask what to wear</button>
|
|
89
|
+
</div>
|
|
90
|
+
);
|
|
91
|
+
}
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
That is the whole integration. The framework bundles the view into one self-contained HTML file, serves it as a `ui://` resource with the `text/html;profile=mcp-app` type, and links it to the tool, following the [MCP Apps specification](https://github.com/modelcontextprotocol/ext-apps), the open standard that Claude, ChatGPT, VS Code and other clients implement.
|
|
95
|
+
|
|
96
|
+
`useTool` gives you:
|
|
97
|
+
|
|
98
|
+
| | |
|
|
99
|
+
|---|---|
|
|
100
|
+
| `input`, `output`, `text` | The arguments the model sent and what your handler returned |
|
|
101
|
+
| `isPending`, `isError` | Where the call is |
|
|
102
|
+
| `callTool(name, args)` | Call any tool on your server from the view |
|
|
103
|
+
| `sendMessage(text)` | Put a message into the conversation |
|
|
104
|
+
| `openLink(url)` | Ask the host to open a link |
|
|
105
|
+
| `theme` | `light` or `dark`, from the host |
|
|
106
|
+
|
|
107
|
+
## The Studio
|
|
108
|
+
|
|
109
|
+
`npm run dev` opens it at `http://localhost:3333`.
|
|
110
|
+
|
|
111
|
+

|
|
112
|
+
|
|
113
|
+
| Page | What it does |
|
|
114
|
+
|---|---|
|
|
115
|
+
| **Overview** | Every MCP server in the folder as a card, with **New MCP server** to start another. Below it, the open server at a glance: tools, views, calls and what to do next. |
|
|
116
|
+
| **Tools** | Every tool, schema first: each input with its type and description, each with an Edit link. A form beside it runs the tool and shows the result and the view. Save a run as a test. Edit the tool code and the view code in place. **New tool** writes one from a description, or adds a blank one. |
|
|
117
|
+
| **Chat** | One test agent for the open server, on your own model key. Ask for a tool or an MCP app and it is written into your project and run in the chat. Tool calls and views appear inline, as they would in a chat client. Set its instructions, switch models, turn tools on and off. |
|
|
118
|
+
| **Canvas** | One canvas for each MCP server: the server on top, its tools under it, every tool with its description and inputs. Drag cards where you want them. Click the server to edit its name and description. Click a tool to edit its schema, run it and change its code beside the canvas. |
|
|
119
|
+
| **Tests** | Every saved test of the server, grouped by tool, with one button to run them all and the reason for each failure. |
|
|
120
|
+
| **Logs** | Every tool call the dev server handled, from the Studio, your editor or any other client, with input, result and time. The last 300 are kept across restarts. |
|
|
121
|
+
| **Connect** | Install buttons for Cursor and VS Code, commands for Claude Code and Codex, and the steps to go live. |
|
|
122
|
+
| **Directory** | Popular servers from [plugmcp.ai](https://plugmcp.ai/mcp) and a search. Add a hosted one to your chat, or open the full directory on plugmcp.ai. |
|
|
123
|
+
|
|
124
|
+
### More than one MCP server
|
|
125
|
+
|
|
126
|
+
A folder can hold several MCP servers. The one in `server.ts` answers at `/mcp`. Each folder in `servers/` is another one, with its own `server.ts` and `views/`, and answers at `/mcp/<name>`. **New MCP server** in the Studio creates one; the switcher at the top of the sidebar chooses which one the Studio works on. Build one on its own with `plugmcp build --root servers/<name>`.
|
|
127
|
+
|
|
128
|
+
Keys are read from your project's `.env` (`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GOOGLE_GENERATIVE_AI_API_KEY`, `OPENROUTER_API_KEY`) or saved from the Studio to `~/.plugmcp/keys.json`.
|
|
129
|
+
|
|
130
|
+
## Use the tools in the Claude Agent SDK
|
|
131
|
+
|
|
132
|
+
```ts
|
|
133
|
+
import { query } from "@anthropic-ai/claude-agent-sdk";
|
|
134
|
+
import { toAgentSdk } from "plugmcp/agent";
|
|
135
|
+
import server from "./server.js";
|
|
136
|
+
|
|
137
|
+
const { mcpServers, allowedTools } = toAgentSdk(server);
|
|
138
|
+
|
|
139
|
+
for await (const message of query({ prompt: "What is the weather in Lisbon?", options: { mcpServers, allowedTools } })) {
|
|
140
|
+
// ...
|
|
141
|
+
}
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
No server to start and no network hop. Scaffold a working example with `npx create-plugmcp my-agent --template agent`, and run it.
|
|
145
|
+
|
|
146
|
+
## Command line
|
|
147
|
+
|
|
148
|
+
| Command | |
|
|
149
|
+
|---|---|
|
|
150
|
+
| `plugmcp dev` | Run every MCP server in the folder and the Studio. Reloads on save. |
|
|
151
|
+
| `plugmcp build` | Bundle the server and its views into `dist/`. |
|
|
152
|
+
| `plugmcp start` | Serve the build over Streamable HTTP at `/mcp`. Add `--stdio` for stdio. Reads `PORT`. |
|
|
153
|
+
| `plugmcp test` | Run the tests saved in the Studio against your code. Exits with 1 when one fails, so it fits CI. |
|
|
154
|
+
| `plugmcp search <words>` | Search the PlugMCP directory. |
|
|
155
|
+
| `plugmcp add <slug>` | Add a directory server to this project's Studio chat. |
|
|
156
|
+
| `plugmcp list` | Give your server a page in the directory. |
|
|
157
|
+
| `plugmcp login` | Save a plugmcp.ai account key on this machine. |
|
|
158
|
+
| `plugmcp deploy --url <url>` | Put a server you already host behind plugmcp.ai. |
|
|
159
|
+
|
|
160
|
+
`list` and `deploy` take `--dry-run` to print what would be sent without sending it.
|
|
161
|
+
|
|
162
|
+
## Going live
|
|
163
|
+
|
|
164
|
+
The framework does not need PlugMCP's cloud. `plugmcp build` produces a plain Node server you can run on Railway, Fly, a container, or your own machine.
|
|
165
|
+
|
|
166
|
+
```bash
|
|
167
|
+
plugmcp build
|
|
168
|
+
plugmcp start
|
|
169
|
+
```
|
|
170
|
+
|
|
171
|
+
When it has a public address, [plugmcp.ai](https://plugmcp.ai) adds what a production server needs:
|
|
172
|
+
|
|
173
|
+
- **A directory page** with install buttons for every client, so people and agents can find it: `plugmcp list --url https://your-host.example/mcp`
|
|
174
|
+
- **A gateway address, API keys you can revoke, a log of every call, and alerts** when it breaks: `plugmcp deploy --url https://your-host.example/mcp`
|
|
175
|
+
- **Toolkits**: one link that combines several servers, so an agent installs them all at once.
|
|
176
|
+
- **No code at all**, if you prefer: plugmcp.ai also builds and hosts MCP servers from a form and a visual canvas. See [plugmcp.ai](https://plugmcp.ai).
|
|
177
|
+
|
|
178
|
+
Every server also answers a browser at its own `/mcp` address with a page listing its tools and how to connect.
|
|
179
|
+
|
|
180
|
+
## Templates
|
|
181
|
+
|
|
182
|
+
| Template | |
|
|
183
|
+
|---|---|
|
|
184
|
+
| `starter` (default) | A weather tool with a view. Real data, no key needed. |
|
|
185
|
+
| `blank` | One tool, nothing else. |
|
|
186
|
+
| `agent` | The starter, plus a script that runs the tools in the Claude Agent SDK. |
|
|
187
|
+
|
|
188
|
+
```bash
|
|
189
|
+
npx create-plugmcp my-server --template blank
|
|
190
|
+
```
|
|
191
|
+
|
|
192
|
+
## How it compares
|
|
193
|
+
|
|
194
|
+
Other good frameworks exist, and you should pick the one that fits.
|
|
195
|
+
|
|
196
|
+
- [mcp-use](https://github.com/mcp-use/mcp-use) is a larger framework with an agent client, an inspector and its own cloud.
|
|
197
|
+
- [NitroStack](https://github.com/nitrocloudofficial/nitrostack) is a NestJS-style framework with modules, decorators and a desktop studio.
|
|
198
|
+
- The official [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk) and [ext-apps](https://github.com/modelcontextprotocol/ext-apps) are what this SDK is built on. Use them directly when you want full control.
|
|
199
|
+
|
|
200
|
+
PlugMCP aims to be the smallest path from an idea to an MCP server or MCP app that you can see, test and talk to on your own machine, with a public directory attached.
|
|
201
|
+
|
|
202
|
+
## Questions
|
|
203
|
+
|
|
204
|
+
**What is an MCP server?** A program that gives an AI model tools to call, over the [Model Context Protocol](https://modelcontextprotocol.io). Claude, ChatGPT, Cursor, VS Code and most agent frameworks can connect to one.
|
|
205
|
+
|
|
206
|
+
**What is an MCP app?** A tool that also returns a small interactive page, shown inside the chat. In PlugMCP it is a tool plus one React file in `views/`.
|
|
207
|
+
|
|
208
|
+
**How do I test an MCP server locally?** `npm run dev` opens the Studio. Run any tool with a form, chat with the server using your own model key, save runs as tests, and run them with `plugmcp test`.
|
|
209
|
+
|
|
210
|
+
**Does it work with Claude, ChatGPT and Cursor?** Yes. The server speaks standard MCP over Streamable HTTP and stdio, and views follow the MCP Apps standard. The **Connect** page has the install steps for each client.
|
|
211
|
+
|
|
212
|
+
**Do I need an account or a PlugMCP key?** No. Everything runs on your machine. A model key is only needed for the chat, and it is your own.
|
|
213
|
+
|
|
214
|
+
**Where can I find existing MCP servers?** The [PlugMCP directory](https://plugmcp.ai/mcp) lists 95,000+, searchable from the Studio and with `plugmcp search`.
|
|
215
|
+
|
|
216
|
+
## Requirements
|
|
217
|
+
|
|
218
|
+
Node 20.19 or newer. Views use React 18 or 19.
|
|
219
|
+
|
|
220
|
+
## Packages
|
|
221
|
+
|
|
222
|
+
| Package | |
|
|
223
|
+
|---|---|
|
|
224
|
+
| [`plugmcp`](packages/plugmcp) | The framework, the command line and the Studio. |
|
|
225
|
+
| [`create-plugmcp`](packages/create-plugmcp) | The project scaffolder. |
|
|
226
|
+
|
|
227
|
+
## Contributing
|
|
228
|
+
|
|
229
|
+
Issues and pull requests are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md). To report a security problem, see [SECURITY.md](SECURITY.md).
|
|
230
|
+
|
|
231
|
+
## License
|
|
232
|
+
|
|
233
|
+
[MIT](LICENSE)
|
package/dist/agent.d.ts
ADDED
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
import type { PlugServer } from "./index.js";
|
|
2
|
+
/**
|
|
3
|
+
* Use a PlugMCP server's tools inside the Claude Agent SDK, in the same
|
|
4
|
+
* process and with no network hop:
|
|
5
|
+
*
|
|
6
|
+
* import { query } from "@anthropic-ai/claude-agent-sdk";
|
|
7
|
+
* import { toAgentSdk } from "plugmcp/agent";
|
|
8
|
+
* import server from "./server.js";
|
|
9
|
+
*
|
|
10
|
+
* const { mcpServers, allowedTools } = toAgentSdk(server);
|
|
11
|
+
* for await (const message of query({ prompt, options: { mcpServers, allowedTools } })) { ... }
|
|
12
|
+
*/
|
|
13
|
+
export declare function toAgentSdk(server: PlugServer): {
|
|
14
|
+
/** Pass as `options.mcpServers`. */
|
|
15
|
+
mcpServers: {
|
|
16
|
+
[x: string]: import("@anthropic-ai/claude-agent-sdk").McpSdkServerConfigWithInstance;
|
|
17
|
+
};
|
|
18
|
+
/** Pass as `options.allowedTools` so the agent may call them without asking. */
|
|
19
|
+
allowedTools: string[];
|
|
20
|
+
};
|
package/dist/agent.js
ADDED
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
import { createSdkMcpServer, tool } from "@anthropic-ai/claude-agent-sdk";
|
|
2
|
+
import { slugify, toToolResult } from "./index.js";
|
|
3
|
+
/**
|
|
4
|
+
* Use a PlugMCP server's tools inside the Claude Agent SDK, in the same
|
|
5
|
+
* process and with no network hop:
|
|
6
|
+
*
|
|
7
|
+
* import { query } from "@anthropic-ai/claude-agent-sdk";
|
|
8
|
+
* import { toAgentSdk } from "plugmcp/agent";
|
|
9
|
+
* import server from "./server.js";
|
|
10
|
+
*
|
|
11
|
+
* const { mcpServers, allowedTools } = toAgentSdk(server);
|
|
12
|
+
* for await (const message of query({ prompt, options: { mcpServers, allowedTools } })) { ... }
|
|
13
|
+
*/
|
|
14
|
+
export function toAgentSdk(server) {
|
|
15
|
+
const name = slugify(server.info.name);
|
|
16
|
+
const tools = [...server.tools.values()].map(({ config, handler }) => {
|
|
17
|
+
// The Agent SDK takes the fields of a Zod object, not the object itself.
|
|
18
|
+
const shape = config.input?.shape ?? {};
|
|
19
|
+
return tool(config.name, config.description ?? config.title ?? config.name, shape, async (args, extra) => {
|
|
20
|
+
try {
|
|
21
|
+
return toToolResult(await handler(args, extra));
|
|
22
|
+
}
|
|
23
|
+
catch (error) {
|
|
24
|
+
const text = error instanceof Error ? error.message : String(error);
|
|
25
|
+
return { content: [{ type: "text", text }], isError: true };
|
|
26
|
+
}
|
|
27
|
+
});
|
|
28
|
+
});
|
|
29
|
+
return {
|
|
30
|
+
/** Pass as `options.mcpServers`. */
|
|
31
|
+
mcpServers: { [name]: createSdkMcpServer({ name, version: server.info.version ?? "0.1.0", tools }) },
|
|
32
|
+
/** Pass as `options.allowedTools` so the agent may call them without asking. */
|
|
33
|
+
allowedTools: [...server.tools.keys()].map((toolName) => `mcp__${name}__${toolName}`),
|
|
34
|
+
};
|
|
35
|
+
}
|
package/dist/build.d.ts
ADDED
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
import type { BuildOptions, PlugServer } from "./index.js";
|
|
2
|
+
export interface BuildResult {
|
|
3
|
+
outDir: string;
|
|
4
|
+
views: string[];
|
|
5
|
+
ms: number;
|
|
6
|
+
}
|
|
7
|
+
/** Bundle the server to dist/server.js and each view to one self-contained HTML file. */
|
|
8
|
+
export declare function buildProject(root: string, entry?: string): Promise<BuildResult>;
|
|
9
|
+
/** Load what `plugmcp build` produced. */
|
|
10
|
+
export declare function loadBuilt(root: string): Promise<{
|
|
11
|
+
server: PlugServer;
|
|
12
|
+
views: NonNullable<BuildOptions["views"]>;
|
|
13
|
+
}>;
|
package/dist/build.js
ADDED
|
@@ -0,0 +1,83 @@
|
|
|
1
|
+
import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
|
|
2
|
+
import { join } from "node:path";
|
|
3
|
+
import { pathToFileURL } from "node:url";
|
|
4
|
+
import react from "@vitejs/plugin-react";
|
|
5
|
+
import { build as viteBuild } from "vite";
|
|
6
|
+
import { viteSingleFile } from "vite-plugin-singlefile";
|
|
7
|
+
import { isPlugServer } from "./index.js";
|
|
8
|
+
import { listViews, resolveProject } from "./dev/project.js";
|
|
9
|
+
import { viewEntryPlugin, viewShell } from "./dev/views.js";
|
|
10
|
+
/** Bundle the server to dist/server.js and each view to one self-contained HTML file. */
|
|
11
|
+
export async function buildProject(root, entry) {
|
|
12
|
+
const started = performance.now();
|
|
13
|
+
const project = resolveProject(root, entry);
|
|
14
|
+
const outDir = join(root, "dist");
|
|
15
|
+
rmSync(outDir, { recursive: true, force: true });
|
|
16
|
+
await viteBuild({
|
|
17
|
+
root,
|
|
18
|
+
configFile: false,
|
|
19
|
+
logLevel: "warn",
|
|
20
|
+
build: {
|
|
21
|
+
ssr: project.entry,
|
|
22
|
+
outDir,
|
|
23
|
+
emptyOutDir: false,
|
|
24
|
+
target: "node20",
|
|
25
|
+
rollupOptions: { output: { format: "esm", entryFileNames: "server.js" } },
|
|
26
|
+
},
|
|
27
|
+
});
|
|
28
|
+
const views = listViews(project);
|
|
29
|
+
const tmp = join(root, ".plugmcp", "build");
|
|
30
|
+
mkdirSync(tmp, { recursive: true });
|
|
31
|
+
mkdirSync(join(outDir, "views"), { recursive: true });
|
|
32
|
+
for (const tool of Object.keys(views)) {
|
|
33
|
+
const page = join(tmp, `${tool}.html`);
|
|
34
|
+
writeFileSync(page, viewShell(tool));
|
|
35
|
+
await viteBuild({
|
|
36
|
+
root,
|
|
37
|
+
configFile: false,
|
|
38
|
+
logLevel: "warn",
|
|
39
|
+
plugins: [react(), viewEntryPlugin(() => views), viteSingleFile()],
|
|
40
|
+
build: { outDir: join(tmp, "out"), emptyOutDir: true, rollupOptions: { input: page } },
|
|
41
|
+
});
|
|
42
|
+
const built = findHtml(join(tmp, "out"));
|
|
43
|
+
if (!built)
|
|
44
|
+
throw new Error(`The view for ${tool} did not produce an HTML file.`);
|
|
45
|
+
writeFileSync(join(outDir, "views", `${tool}.html`), readFileSync(built));
|
|
46
|
+
}
|
|
47
|
+
rmSync(tmp, { recursive: true, force: true });
|
|
48
|
+
return { outDir, views: Object.keys(views), ms: Math.round(performance.now() - started) };
|
|
49
|
+
}
|
|
50
|
+
function findHtml(dir) {
|
|
51
|
+
for (const item of readdirSync(dir, { withFileTypes: true })) {
|
|
52
|
+
const path = join(dir, item.name);
|
|
53
|
+
if (item.isDirectory()) {
|
|
54
|
+
const inner = findHtml(path);
|
|
55
|
+
if (inner)
|
|
56
|
+
return inner;
|
|
57
|
+
}
|
|
58
|
+
else if (item.name.endsWith(".html"))
|
|
59
|
+
return path;
|
|
60
|
+
}
|
|
61
|
+
return undefined;
|
|
62
|
+
}
|
|
63
|
+
/** Load what `plugmcp build` produced. */
|
|
64
|
+
export async function loadBuilt(root) {
|
|
65
|
+
const file = join(root, "dist", "server.js");
|
|
66
|
+
if (!existsSync(file))
|
|
67
|
+
throw new Error("No build found. Run `plugmcp build` first.");
|
|
68
|
+
const module = (await import(pathToFileURL(file).href));
|
|
69
|
+
const server = module.default ?? module.server;
|
|
70
|
+
if (!isPlugServer(server))
|
|
71
|
+
throw new Error('dist/server.js does not default-export a server. Add "export default server".');
|
|
72
|
+
const views = {};
|
|
73
|
+
const dir = join(root, "dist", "views");
|
|
74
|
+
if (existsSync(dir)) {
|
|
75
|
+
for (const name of readdirSync(dir)) {
|
|
76
|
+
if (!name.endsWith(".html"))
|
|
77
|
+
continue;
|
|
78
|
+
const html = readFileSync(join(dir, name), "utf8");
|
|
79
|
+
views[name.slice(0, -5)] = { html: () => html };
|
|
80
|
+
}
|
|
81
|
+
}
|
|
82
|
+
return { server, views };
|
|
83
|
+
}
|
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
import { Client } from "@modelcontextprotocol/client";
|
|
2
|
+
export declare function readAccountKey(): string | undefined;
|
|
3
|
+
export declare function saveAccountKey(key: string): void;
|
|
4
|
+
export interface Listing {
|
|
5
|
+
name: string;
|
|
6
|
+
description: string;
|
|
7
|
+
remoteUrl?: string;
|
|
8
|
+
repoUrl?: string;
|
|
9
|
+
homepageUrl?: string;
|
|
10
|
+
npm?: string;
|
|
11
|
+
}
|
|
12
|
+
export declare const SUBMIT_URL = "https://plugmcp.ai/api/directory/submit";
|
|
13
|
+
export declare function submitListing(listing: Listing): Promise<Record<string, unknown>>;
|
|
14
|
+
export declare const ACCOUNT_MCP_URL = "https://plugmcp.ai/account-mcp";
|
|
15
|
+
export declare function accountClient(key: string): Promise<Client>;
|
|
16
|
+
/**
|
|
17
|
+
* Whether the account MCP can register a server that already runs at an address.
|
|
18
|
+
* Checked live, so the CLI starts working the day plugmcp.ai adds it.
|
|
19
|
+
*/
|
|
20
|
+
export declare function canWrapUrl(client: Client): Promise<boolean>;
|
|
@@ -0,0 +1,56 @@
|
|
|
1
|
+
import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
|
|
2
|
+
import { join } from "node:path";
|
|
3
|
+
import { Client, StreamableHTTPClientTransport } from "@modelcontextprotocol/client";
|
|
4
|
+
import { configDir } from "../dev/keys.js";
|
|
5
|
+
import { DIRECTORY_URL } from "../install.js";
|
|
6
|
+
/** Everything that talks to plugmcp.ai. Nothing here runs unless the user asks for it. */
|
|
7
|
+
const credentialsPath = () => join(configDir(), "credentials.json");
|
|
8
|
+
export function readAccountKey() {
|
|
9
|
+
if (process.env.PLUGMCP_ACCOUNT_KEY)
|
|
10
|
+
return process.env.PLUGMCP_ACCOUNT_KEY;
|
|
11
|
+
try {
|
|
12
|
+
return JSON.parse(readFileSync(credentialsPath(), "utf8")).accountKey;
|
|
13
|
+
}
|
|
14
|
+
catch {
|
|
15
|
+
return undefined;
|
|
16
|
+
}
|
|
17
|
+
}
|
|
18
|
+
export function saveAccountKey(key) {
|
|
19
|
+
if (!/^pb_acct_[A-Za-z0-9]{40}$/.test(key)) {
|
|
20
|
+
throw new Error("That is not an account key. Account keys start with pb_acct_ and are created at plugmcp.ai/app/settings/agent-access.");
|
|
21
|
+
}
|
|
22
|
+
if (!existsSync(configDir()))
|
|
23
|
+
mkdirSync(configDir(), { recursive: true });
|
|
24
|
+
writeFileSync(credentialsPath(), JSON.stringify({ accountKey: key }, null, 2), { mode: 0o600 });
|
|
25
|
+
}
|
|
26
|
+
export const SUBMIT_URL = `${DIRECTORY_URL}/api/directory/submit`;
|
|
27
|
+
export async function submitListing(listing) {
|
|
28
|
+
const response = await fetch(SUBMIT_URL, {
|
|
29
|
+
method: "POST",
|
|
30
|
+
headers: { "content-type": "application/json", "user-agent": "plugmcp-sdk" },
|
|
31
|
+
body: JSON.stringify(listing),
|
|
32
|
+
signal: AbortSignal.timeout(30_000),
|
|
33
|
+
});
|
|
34
|
+
const body = (await response.json().catch(() => ({})));
|
|
35
|
+
if (!response.ok)
|
|
36
|
+
throw new Error(String(body.error ?? `The directory answered ${response.status}.`));
|
|
37
|
+
return body;
|
|
38
|
+
}
|
|
39
|
+
export const ACCOUNT_MCP_URL = `${DIRECTORY_URL}/account-mcp`;
|
|
40
|
+
export async function accountClient(key) {
|
|
41
|
+
const client = new Client({ name: "plugmcp-cli", version: "0.1.0" });
|
|
42
|
+
await client.connect(new StreamableHTTPClientTransport(new URL(ACCOUNT_MCP_URL), {
|
|
43
|
+
requestInit: { headers: { authorization: `Bearer ${key}` } },
|
|
44
|
+
}));
|
|
45
|
+
return client;
|
|
46
|
+
}
|
|
47
|
+
/**
|
|
48
|
+
* Whether the account MCP can register a server that already runs at an address.
|
|
49
|
+
* Checked live, so the CLI starts working the day plugmcp.ai adds it.
|
|
50
|
+
*/
|
|
51
|
+
export async function canWrapUrl(client) {
|
|
52
|
+
const { tools } = await client.listTools();
|
|
53
|
+
const create = tools.find((tool) => tool.name === "create_server");
|
|
54
|
+
const properties = (create?.inputSchema.properties ?? {});
|
|
55
|
+
return "upstream_url" in properties;
|
|
56
|
+
}
|