xmcp 0.0.14 → 0.0.16
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/README.md +97 -79
- package/dist/cli.js +2 -2
- package/dist/compile.d.ts +8 -3
- package/dist/index.d.ts +1 -0
- package/dist/index.js +1 -1
- package/dist/runtime/169.js +2 -0
- package/dist/runtime/169.js.LICENSE.txt +1 -0
- package/dist/runtime/382.js +1 -0
- package/dist/runtime/450.js +2 -0
- package/dist/runtime/headers.js +1 -1
- package/dist/runtime/http.js +1 -0
- package/dist/runtime/stdio.js +1 -1
- package/dist/runtime/transports/http/http-context.d.ts +9 -0
- package/dist/utils/context.d.ts +30 -0
- package/dist/utils/get-webpack-config.d.ts +2 -3
- package/dist/utils/parse-config.d.ts +36 -98
- package/package.json +4 -3
- package/dist/cli.d.ts +0 -2
- package/dist/platforms/build-vercel-output.d.ts +0 -2
- package/dist/runtime/http-context.d.ts +0 -9
- package/dist/runtime/shared.js +0 -2
- package/dist/runtime/sse.js +0 -1
- package/dist/runtime/streamable-http.js +0 -1
- /package/dist/runtime/{shared.js.LICENSE.txt → 450.js.LICENSE.txt} +0 -0
package/README.md
CHANGED
|
@@ -2,29 +2,26 @@
|
|
|
2
2
|
|
|
3
3
|
**The MCP Framework**
|
|
4
4
|
|
|
5
|
-
XMCP is
|
|
5
|
+
XMCP is framework for building and shipping MCP applications. Designed with DX in mind, it streamlines development and lowers the barrier to entry for anyone looking to create and deploy powerful tools on top of the MCP ecosystem.
|
|
6
6
|
|
|
7
7
|
The framework handles complex tasks like transports, building and authentication, so developers can focus on what matters most: coding the tools, resources, or clients they want to bring to life.
|
|
8
8
|
|
|
9
9
|
## Features
|
|
10
10
|
|
|
11
11
|
- 🚀 **Hot Reloading** - Instant development feedback with automatic rebuilds
|
|
12
|
-
- 🔍 **
|
|
12
|
+
- 🔍 **File system routing** - Tools are automatically discovered and registered from `src/tools` directory.
|
|
13
13
|
- 📝 **TypeScript First** - Full TypeScript support with type inference
|
|
14
14
|
- 🎯 **Schema Validation** - Built-in parameter validation with Zod
|
|
15
15
|
- 🛠️ **Rich Tooling** - Built-in CLI for development and building
|
|
16
16
|
- 🔌 **MCP Compatible** - Full compatibility with Model Context Protocol
|
|
17
|
+
- 📡 **STDIO Transport** - Standard I/O transport for local MCP servers
|
|
18
|
+
- 🌐 **HTTP Transport** - Stramable HTTP transport for web-based MCP servers
|
|
19
|
+
- 🔧 **Middleware Support** - Extensible middleware system for request/response processing
|
|
20
|
+
- 🚀 **Deploy Anywhere** - Deploy to any platform.
|
|
21
|
+
- 📦 **Vercel Support** - Built-in support for Vercel deployment
|
|
17
22
|
|
|
18
23
|
## Quick Start
|
|
19
24
|
|
|
20
|
-
### Installation
|
|
21
|
-
|
|
22
|
-
```bash
|
|
23
|
-
npm install xmcp zod @modelcontextprotocol/sdk
|
|
24
|
-
```
|
|
25
|
-
|
|
26
|
-
### Create Your First Project
|
|
27
|
-
|
|
28
25
|
The fastest way to get started is with the project generator:
|
|
29
26
|
|
|
30
27
|
```bash
|
|
@@ -33,38 +30,71 @@ cd my-mcp-server
|
|
|
33
30
|
npm run dev
|
|
34
31
|
```
|
|
35
32
|
|
|
36
|
-
|
|
33
|
+
## Project structure
|
|
37
34
|
|
|
38
|
-
|
|
35
|
+
A basic project structure is as follows:
|
|
39
36
|
|
|
40
37
|
```
|
|
41
38
|
my-project/
|
|
42
39
|
├── src/
|
|
43
|
-
│
|
|
44
|
-
│
|
|
40
|
+
│ ├── middleware.ts # Middleware for http request/response processing
|
|
41
|
+
│ └── tools/ # Tool files are auto-discovered here
|
|
42
|
+
│ ├── add.ts
|
|
43
|
+
│ ├── multiply.ts
|
|
44
|
+
├── dist/ # Built output (generated)
|
|
45
45
|
├── package.json
|
|
46
|
-
|
|
46
|
+
├── tsconfig.json
|
|
47
|
+
└── xmcp.config.ts # Configuration file for xmcp
|
|
47
48
|
```
|
|
48
49
|
|
|
49
|
-
|
|
50
|
+
## Creating Tools
|
|
51
|
+
|
|
52
|
+
MXCP detects files under `src/tools/` directory and registers them as tools.
|
|
53
|
+
|
|
54
|
+
The tool file should export three elements:
|
|
50
55
|
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
56
|
+
- `schema`: The input parameters using Zod schemas
|
|
57
|
+
- `metadata`: The tool's identity and behavior hints
|
|
58
|
+
- `default`: The tool handler function
|
|
59
|
+
|
|
60
|
+
Example of a tool file:
|
|
61
|
+
|
|
62
|
+
```typescript
|
|
63
|
+
// src/tools/add.ts
|
|
64
|
+
|
|
65
|
+
import { z } from "zod";
|
|
66
|
+
import { type InferSchema } from "xmcp";
|
|
67
|
+
|
|
68
|
+
// 1. Schema - Define input parameters
|
|
69
|
+
export const schema = {
|
|
70
|
+
a: z.number().describe("First number to add"),
|
|
71
|
+
b: z.number().describe("Second number to add"),
|
|
72
|
+
};
|
|
73
|
+
|
|
74
|
+
// 2. Metadata - Define tool identity and hints
|
|
75
|
+
export const metadata = {
|
|
76
|
+
name: "add",
|
|
77
|
+
description: "Add two numbers together",
|
|
78
|
+
annotations: {
|
|
79
|
+
title: "Add Two Numbers",
|
|
80
|
+
readOnlyHint: true,
|
|
81
|
+
destructiveHint: false,
|
|
82
|
+
idempotentHint: true,
|
|
83
|
+
},
|
|
84
|
+
};
|
|
85
|
+
|
|
86
|
+
// 3. Implementation - The actual tool logic
|
|
87
|
+
export default async function add({ a, b }: InferSchema<typeof schema>) {
|
|
88
|
+
return {
|
|
89
|
+
content: [{ type: "text", text: String(a + b) }],
|
|
90
|
+
};
|
|
57
91
|
}
|
|
58
92
|
```
|
|
59
93
|
|
|
60
|
-
##
|
|
61
|
-
|
|
62
|
-
XMCP tools follow a simple but powerful pattern, with separation of concerns as our premise. Each tool is a TypeScript file that exports exactly **three elements**:
|
|
94
|
+
## Tool file structure
|
|
63
95
|
|
|
64
96
|
### 1. Schema (Required)
|
|
65
97
|
|
|
66
|
-
Define the input parameters using Zod schemas:
|
|
67
|
-
|
|
68
98
|
```typescript
|
|
69
99
|
import { z } from "zod";
|
|
70
100
|
|
|
@@ -125,40 +155,6 @@ The implementation function:
|
|
|
125
155
|
- **Return**: MCP-compatible response with content array
|
|
126
156
|
- **Async**: Supports async operations for API calls, file I/O, etc.
|
|
127
157
|
|
|
128
|
-
## Complete Tool Example
|
|
129
|
-
|
|
130
|
-
Here's a complete tool file (`src/tools/add.ts`):
|
|
131
|
-
|
|
132
|
-
```typescript
|
|
133
|
-
import { z } from "zod";
|
|
134
|
-
import { type InferSchema } from "xmcp";
|
|
135
|
-
|
|
136
|
-
// 1. Schema - Define input parameters
|
|
137
|
-
export const schema = {
|
|
138
|
-
a: z.number().describe("First number to add"),
|
|
139
|
-
b: z.number().describe("Second number to add"),
|
|
140
|
-
};
|
|
141
|
-
|
|
142
|
-
// 2. Metadata - Define tool identity and hints
|
|
143
|
-
export const metadata = {
|
|
144
|
-
name: "add",
|
|
145
|
-
description: "Add two numbers together",
|
|
146
|
-
annotations: {
|
|
147
|
-
title: "Add Two Numbers",
|
|
148
|
-
readOnlyHint: true,
|
|
149
|
-
destructiveHint: false,
|
|
150
|
-
idempotentHint: true,
|
|
151
|
-
},
|
|
152
|
-
};
|
|
153
|
-
|
|
154
|
-
// 3. Implementation - The actual tool logic
|
|
155
|
-
export default async function add({ a, b }: InferSchema<typeof schema>) {
|
|
156
|
-
return {
|
|
157
|
-
content: [{ type: "text", text: String(a + b) }],
|
|
158
|
-
};
|
|
159
|
-
}
|
|
160
|
-
```
|
|
161
|
-
|
|
162
158
|
## Development Commands
|
|
163
159
|
|
|
164
160
|
```bash
|
|
@@ -171,22 +167,8 @@ npm run build
|
|
|
171
167
|
# Start built server (stdio transport)
|
|
172
168
|
node dist/stdio.js
|
|
173
169
|
|
|
174
|
-
# Start built server (
|
|
175
|
-
node dist/
|
|
176
|
-
```
|
|
177
|
-
|
|
178
|
-
## Project Structure
|
|
179
|
-
|
|
180
|
-
```
|
|
181
|
-
your-project/
|
|
182
|
-
├── src/
|
|
183
|
-
│ └── tools/ # Tool files are auto-discovered here
|
|
184
|
-
│ ├── add.ts # Your tools (each exports schema, metadata, default)
|
|
185
|
-
│ ├── multiply.ts
|
|
186
|
-
│ └── fetch.ts
|
|
187
|
-
├── dist/ # Built output (generated)
|
|
188
|
-
├── package.json
|
|
189
|
-
└── tsconfig.json
|
|
170
|
+
# Start built server (HTTP transport)
|
|
171
|
+
node dist/http.js
|
|
190
172
|
```
|
|
191
173
|
|
|
192
174
|
## Key Concepts
|
|
@@ -206,7 +188,7 @@ your-project/
|
|
|
206
188
|
### MCP Compatibility
|
|
207
189
|
|
|
208
190
|
- Tools return MCP-compatible response objects
|
|
209
|
-
- Supports both `stdio` and `
|
|
191
|
+
- Supports both `stdio` and `http` transports
|
|
210
192
|
- Full compatibility with MCP clients and AI models
|
|
211
193
|
|
|
212
194
|
## Vercel Deployment
|
|
@@ -217,4 +199,40 @@ XMCP can be deployed to Vercel with the `--vercel` flag. This will create `.verc
|
|
|
217
199
|
xmcp build --vercel
|
|
218
200
|
```
|
|
219
201
|
|
|
220
|
-
|
|
202
|
+
## Middlewares
|
|
203
|
+
|
|
204
|
+
When building HTTP MCP servers, you can use middlewares to process the request and response.
|
|
205
|
+
|
|
206
|
+
To get started, create a `src/middleware.ts` file with the following content:
|
|
207
|
+
|
|
208
|
+
```typescript
|
|
209
|
+
import { type Middleware } from "xmcp";
|
|
210
|
+
|
|
211
|
+
export const middleware: Middleware = async (req, next) => {
|
|
212
|
+
const headers = headers();
|
|
213
|
+
const accept = headers["accept"];
|
|
214
|
+
return next();
|
|
215
|
+
};
|
|
216
|
+
```
|
|
217
|
+
|
|
218
|
+
The middleware function receives the request and the next function to call. You can use the `next` function to call the next middleware or the tool.
|
|
219
|
+
|
|
220
|
+
## xmcp/headers
|
|
221
|
+
|
|
222
|
+
If you are building an `http` mcp server, you can access the request headers using the `xmcp/headers` module.
|
|
223
|
+
|
|
224
|
+
```typescript
|
|
225
|
+
import { headers } from "xmcp/headers";
|
|
226
|
+
|
|
227
|
+
export default async function add({ a, b }: InferSchema<typeof schema>) {
|
|
228
|
+
const headers = headers();
|
|
229
|
+
const accept = headers["accept"];
|
|
230
|
+
return {
|
|
231
|
+
content: [{ type: "text", text: `Accept: ${accept}` }],
|
|
232
|
+
};
|
|
233
|
+
}
|
|
234
|
+
```
|
|
235
|
+
|
|
236
|
+
---
|
|
237
|
+
|
|
238
|
+
From the [basement.studio](https://basement.studio)
|