xmcp 0.0.3 → 0.0.5
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 +212 -0
- package/package.json +2 -3
package/README.md
ADDED
|
@@ -0,0 +1,212 @@
|
|
|
1
|
+
# XMCP
|
|
2
|
+
|
|
3
|
+
**The MCP Framework**
|
|
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.
|
|
6
|
+
|
|
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
|
+
|
|
9
|
+
## Features
|
|
10
|
+
|
|
11
|
+
- 🚀 **Hot Reloading** - Instant development feedback with automatic rebuilds
|
|
12
|
+
- 🔍 **Auto Discovery** - Tools are automatically discovered and registered
|
|
13
|
+
- 📝 **TypeScript First** - Full TypeScript support with type inference
|
|
14
|
+
- 🎯 **Schema Validation** - Built-in parameter validation with Zod
|
|
15
|
+
- 🛠️ **Rich Tooling** - Built-in CLI for development and building
|
|
16
|
+
- 🔌 **MCP Compatible** - Full compatibility with Model Context Protocol
|
|
17
|
+
|
|
18
|
+
## Quick Start
|
|
19
|
+
|
|
20
|
+
### Installation
|
|
21
|
+
|
|
22
|
+
```bash
|
|
23
|
+
npm install xmcp zod @modelcontextprotocol/sdk
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
### Create Your First Project
|
|
27
|
+
|
|
28
|
+
The fastest way to get started is with the project generator:
|
|
29
|
+
|
|
30
|
+
```bash
|
|
31
|
+
npx create-xmcp-app my-mcp-server
|
|
32
|
+
cd my-mcp-server
|
|
33
|
+
npm run dev
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
### Manual Setup
|
|
37
|
+
|
|
38
|
+
Create a basic project structure:
|
|
39
|
+
|
|
40
|
+
```
|
|
41
|
+
my-project/
|
|
42
|
+
├── src/
|
|
43
|
+
│ └── tools/
|
|
44
|
+
│ └── add.ts
|
|
45
|
+
├── package.json
|
|
46
|
+
└── tsconfig.json
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
Add the development and build scripts to your `package.json`:
|
|
50
|
+
|
|
51
|
+
```json
|
|
52
|
+
{
|
|
53
|
+
"scripts": {
|
|
54
|
+
"build": "xmcp build",
|
|
55
|
+
"dev": "xmcp dev"
|
|
56
|
+
}
|
|
57
|
+
}
|
|
58
|
+
```
|
|
59
|
+
|
|
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**:
|
|
63
|
+
|
|
64
|
+
### 1. Schema (Required)
|
|
65
|
+
|
|
66
|
+
Define the input parameters using Zod schemas:
|
|
67
|
+
|
|
68
|
+
```typescript
|
|
69
|
+
import { z } from "zod";
|
|
70
|
+
|
|
71
|
+
export const schema = {
|
|
72
|
+
a: z.number().describe("First number to add"),
|
|
73
|
+
b: z.number().describe("Second number to add"),
|
|
74
|
+
};
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
The schema object defines the tool's parameters with:
|
|
78
|
+
|
|
79
|
+
- **Key**: Parameter name
|
|
80
|
+
- **Value**: Zod schema with `.describe()` for documentation. This will be visibile through the inspector.
|
|
81
|
+
- **Purpose**: Type validation and automatic parameter documentation.
|
|
82
|
+
|
|
83
|
+
### 2. Metadata (Required)
|
|
84
|
+
|
|
85
|
+
Define the tool's identity and behavior hints:
|
|
86
|
+
|
|
87
|
+
```typescript
|
|
88
|
+
export const metadata = {
|
|
89
|
+
name: "add",
|
|
90
|
+
description: "Add two numbers together",
|
|
91
|
+
annotations: {
|
|
92
|
+
title: "Add Two Numbers", // Human-readable display name
|
|
93
|
+
readOnlyHint: true, // true = doesn't modify external state
|
|
94
|
+
destructiveHint: false, // true = performs destructive operations
|
|
95
|
+
idempotentHint: true, // true = same inputs = same outputs
|
|
96
|
+
},
|
|
97
|
+
};
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
The metadata object provides:
|
|
101
|
+
|
|
102
|
+
- **name**: Unique identifier for the tool
|
|
103
|
+
- **description**: Brief explanation of what the tool does
|
|
104
|
+
- **annotations**: Behavioral hints for AI models and UIs
|
|
105
|
+
|
|
106
|
+
This extends entirely from the MCP library.
|
|
107
|
+
|
|
108
|
+
### 3. Implementation (Required)
|
|
109
|
+
|
|
110
|
+
The default export function that performs the actual work:
|
|
111
|
+
|
|
112
|
+
```typescript
|
|
113
|
+
import { type InferSchema } from "xmcp";
|
|
114
|
+
|
|
115
|
+
export default async function add({ a, b }: InferSchema<typeof schema>) {
|
|
116
|
+
return {
|
|
117
|
+
content: [{ type: "text", text: String(a + b) }],
|
|
118
|
+
};
|
|
119
|
+
}
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
The implementation function:
|
|
123
|
+
|
|
124
|
+
- **Parameters**: Automatically typed from your schema using the built-in `InferSchema`
|
|
125
|
+
- **Return**: MCP-compatible response with content array
|
|
126
|
+
- **Async**: Supports async operations for API calls, file I/O, etc.
|
|
127
|
+
|
|
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
|
+
## Development Commands
|
|
163
|
+
|
|
164
|
+
```bash
|
|
165
|
+
# Start development server with hot reloading
|
|
166
|
+
npm run dev
|
|
167
|
+
|
|
168
|
+
# Build for production
|
|
169
|
+
npm run build
|
|
170
|
+
|
|
171
|
+
# Start built server (stdio transport)
|
|
172
|
+
node dist/stdio.js
|
|
173
|
+
|
|
174
|
+
# Start built server (SSE transport)
|
|
175
|
+
node dist/sse.js
|
|
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
|
|
190
|
+
```
|
|
191
|
+
|
|
192
|
+
## Key Concepts
|
|
193
|
+
|
|
194
|
+
### Tool Discovery
|
|
195
|
+
|
|
196
|
+
- Tools are automatically discovered from the `src/tools/` directory
|
|
197
|
+
- Each `.ts` file becomes a tool
|
|
198
|
+
- No manual registration required
|
|
199
|
+
|
|
200
|
+
### Type Safety
|
|
201
|
+
|
|
202
|
+
- `InferSchema<typeof schema>` provides full TypeScript type inference
|
|
203
|
+
- Parameters are automatically validated against your Zod schemas
|
|
204
|
+
- Compile-time type checking for tool implementations
|
|
205
|
+
|
|
206
|
+
### MCP Compatibility
|
|
207
|
+
|
|
208
|
+
- Tools return MCP-compatible response objects
|
|
209
|
+
- Supports both `stdio` and `sse` transports
|
|
210
|
+
- Full compatibility with MCP clients and AI models
|
|
211
|
+
|
|
212
|
+
From the basement.
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "xmcp",
|
|
3
3
|
"description": "The MCP framework",
|
|
4
|
-
"version": "0.0.
|
|
4
|
+
"version": "0.0.5",
|
|
5
5
|
"type": "commonjs",
|
|
6
6
|
"main": "./dist/index.js",
|
|
7
7
|
"types": "./dist/index.d.ts",
|
|
@@ -35,8 +35,7 @@
|
|
|
35
35
|
"tsx": "^4.19.4",
|
|
36
36
|
"webpack": "^5.99.7",
|
|
37
37
|
"webpack-node-externals": "^3.0.0",
|
|
38
|
-
"webpack-virtual-modules": "^0.5.0"
|
|
39
|
-
"eslint-config-custom": "workspace:"
|
|
38
|
+
"webpack-virtual-modules": "^0.5.0"
|
|
40
39
|
},
|
|
41
40
|
"devDependencies": {
|
|
42
41
|
"@types/fs-extra": "^11.0.4",
|