xmcp 0.0.15 → 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.
Files changed (2) hide show
  1. package/README.md +94 -76
  2. package/package.json +2 -2
package/README.md CHANGED
@@ -2,29 +2,26 @@
2
2
 
3
3
  **The MCP Framework**
4
4
 
5
- XMCP is a production-ready 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.
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
- - 🔍 **Auto Discovery** - Tools are automatically discovered and registered
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
- ### Manual Setup
33
+ ## Project structure
37
34
 
38
- Create a basic project structure:
35
+ A basic project structure is as follows:
39
36
 
40
37
  ```
41
38
  my-project/
42
39
  ├── src/
43
- │ └── tools/
44
- │ └── add.ts
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
- └── tsconfig.json
46
+ ├── tsconfig.json
47
+ └── xmcp.config.ts # Configuration file for xmcp
47
48
  ```
48
49
 
49
- Add the development and build scripts to your `package.json`:
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
- ```json
52
- {
53
- "scripts": {
54
- "build": "xmcp build",
55
- "dev": "xmcp dev"
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
- ## Creating Tools
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
@@ -175,20 +171,6 @@ node dist/stdio.js
175
171
  node dist/http.js
176
172
  ```
177
173
 
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
190
- ```
191
-
192
174
  ## Key Concepts
193
175
 
194
176
  ### Tool Discovery
@@ -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
- From the basement.
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)
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "xmcp",
3
3
  "description": "The MCP framework",
4
- "version": "0.0.15",
4
+ "version": "0.0.16",
5
5
  "author": {
6
6
  "name": "Basement Studio",
7
7
  "email": "hello@basement.studio",
@@ -24,7 +24,7 @@
24
24
  "type": "git",
25
25
  "url": "https://github.com/basementstudio/xmcp"
26
26
  },
27
- "homepage": "https://xmcp.run",
27
+ "homepage": "https://xmcp.dev",
28
28
  "type": "commonjs",
29
29
  "main": "./dist/index.js",
30
30
  "types": "./dist/index.d.ts",