xmcp 0.0.4 → 0.0.6

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 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.