xmcp 0.0.15 → 0.0.17-alpha-001

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 (54) hide show
  1. package/README.md +34 -207
  2. package/dist/auth/api-key.d.ts +13 -3
  3. package/dist/auth/jwt.d.ts +20 -1
  4. package/dist/auth/oauth/factory.d.ts +12 -0
  5. package/dist/auth/oauth/index.d.ts +5 -0
  6. package/dist/auth/oauth/providers/proxy-provider.d.ts +13 -0
  7. package/dist/auth/oauth/router.d.ts +4 -0
  8. package/dist/auth/oauth/storage/memory-storage.d.ts +12 -0
  9. package/dist/auth/oauth/types.d.ts +112 -0
  10. package/dist/cli.js +2 -2
  11. package/dist/cli.js.LICENSE.txt +6 -0
  12. package/dist/compiler/compiler-context.d.ts +19 -0
  13. package/dist/compiler/generate-import-code.d.ts +1 -0
  14. package/dist/compiler/get-webpack-config/get-entries.d.ts +3 -0
  15. package/dist/compiler/get-webpack-config/get-injected-variables.d.ts +7 -0
  16. package/dist/compiler/get-webpack-config/index.d.ts +4 -0
  17. package/dist/compiler/get-webpack-config/resolve-tsconfig-paths.d.ts +9 -0
  18. package/dist/compiler/index.d.ts +6 -0
  19. package/dist/compiler/on-first-build.d.ts +3 -0
  20. package/dist/{utils/parse-config.d.ts → compiler/parse-xmcp-config.d.ts} +121 -0
  21. package/dist/compiler/start-http-server.d.ts +1 -0
  22. package/dist/index.d.ts +7 -5
  23. package/dist/index.js +1 -1
  24. package/dist/runtime/118.js +2 -0
  25. package/dist/runtime/118.js.LICENSE.txt +51 -0
  26. package/dist/runtime/267.js +1 -0
  27. package/dist/runtime/382.js +1 -1
  28. package/dist/runtime/386.js +2 -0
  29. package/dist/runtime/562.js +2 -0
  30. package/dist/runtime/{450.js.LICENSE.txt → 562.js.LICENSE.txt} +0 -53
  31. package/dist/runtime/895.js +1 -0
  32. package/dist/runtime/adapter-express.js +2 -0
  33. package/dist/runtime/adapter-express.js.LICENSE.txt +15 -0
  34. package/dist/runtime/adapter-nextjs.js +1 -0
  35. package/dist/runtime/headers.js +1 -1
  36. package/dist/runtime/http.js +2 -1
  37. package/dist/runtime/http.js.LICENSE.txt +15 -0
  38. package/dist/runtime/stdio.js +1 -1
  39. package/dist/types/declarations.d.ts +3 -0
  40. package/dist/types/middleware.d.ts +1 -1
  41. package/dist/utils/cli-icons.d.ts +3 -0
  42. package/dist/utils/constants.d.ts +1 -0
  43. package/dist/utils/context.d.ts +3 -0
  44. package/dist/utils/file-watcher.d.ts +18 -0
  45. package/dist/utils/subscribable.d.ts +12 -0
  46. package/package.json +20 -9
  47. package/dist/compile.d.ts +0 -13
  48. package/dist/declarations.d.ts +0 -3
  49. package/dist/runtime/169.js +0 -2
  50. package/dist/runtime/450.js +0 -2
  51. package/dist/utils/generate-import-code.d.ts +0 -1
  52. package/dist/utils/get-webpack-config.d.ts +0 -3
  53. /package/dist/{utils → compiler}/generate-env-code.d.ts +0 -0
  54. /package/dist/runtime/{169.js.LICENSE.txt → 386.js.LICENSE.txt} +0 -0
package/README.md CHANGED
@@ -1,220 +1,47 @@
1
- # XMCP
1
+ <div align="center">
2
+ <a href="https://xmcp.dev">
3
+ <picture>
4
+ <source media="(prefers-color-scheme: dark)" srcset="https://assets.basehub.com/bf7c3bb1/00bc035af33e78f6ebf4d1978071e248/favicon.png">
5
+ <img alt="XMCP logo" src="https://assets.basehub.com/bf7c3bb1/00bc035af33e78f6ebf4d1978071e248/favicon.png" height="128">
6
+ </picture>
7
+ </a>
8
+ <h1>xmcp</h1>
2
9
 
3
- **The MCP Framework**
10
+ <a href="https://basement.studio"><img alt="XMCP logo" src="https://img.shields.io/badge/MADE%20BY%20basement.studio-000000.svg?style=for-the-badge&labelColor=000"></a>
11
+ <a href="https://www.npmjs.com/package/xmcp"><img alt="NPM version" src="https://img.shields.io/npm/v/xmcp.svg?style=for-the-badge&labelColor=000000"></a>
12
+ <a href="https://github.com/basementstudio/xmcp/blob/main/license.md"><img alt="License" src="https://img.shields.io/npm/l/xmcp.svg?style=for-the-badge&labelColor=000000"></a>
4
13
 
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.
14
+ </div>
6
15
 
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
- ```
16
+ ## The TypeScript MCP Framework
99
17
 
100
- The metadata object provides:
18
+ Xmcp is framework for building and shipping MCP applications with TypeScript. 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.
101
19
 
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 (HTTP transport)
175
- node dist/http.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
20
+ 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.
199
21
 
200
- ### Type Safety
22
+ ## Getting Started
201
23
 
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
24
+ - Visit [xmcp.dev](https://xmcp.dev) to learn more about the project.
25
+ - Visit [xmcp.dev/docs](https://xmcp.dev/docs) to view the full documentation.
205
26
 
206
- ### MCP Compatibility
27
+ ## Features
207
28
 
208
- - Tools return MCP-compatible response objects
209
- - Supports both `stdio` and `http` transports
210
- - Full compatibility with MCP clients and AI models
29
+ - **Hot Reloading** - Instant development feedback with automatic rebuilds
30
+ - **File system routing** - Tools are automatically discovered and registered from `src/tools` directory.
31
+ - **TypeScript First** - Full TypeScript support with type inference
32
+ - **Schema Validation** - Built-in parameter validation with Zod
33
+ - **Rich Tooling** - Built-in CLI for development and building
34
+ - **MCP Compatible** - Full compatibility with Model Context Protocol
35
+ - **STDIO Transport** - Standard I/O transport for local MCP servers
36
+ - **HTTP Transport** - Stramable HTTP transport for web-based MCP servers
37
+ - **Middleware Support** - Extensible middleware system for request/response processing
38
+ - **Deploy Anywhere** - Deploy to any platform.
39
+ - **Vercel Support** - Built-in support for Vercel deployment
211
40
 
212
- ## Vercel Deployment
41
+ ## Security
213
42
 
214
- XMCP can be deployed to Vercel with the `--vercel` flag. This will create `.vercel` directory with the built output.
43
+ If you believe you have found a security vulnerability, we encourage you to let us know right away.
215
44
 
216
- ```bash
217
- xmcp build --vercel
218
- ```
45
+ We will investigate all legitimate reports and do our best to quickly fix the problem.
219
46
 
220
- From the basement.
47
+ Please report any vulnerabilities in our open source repositories to [security@basement.studio](mailto:security@basement.studio).
@@ -1,6 +1,16 @@
1
1
  import { RequestHandler } from "express";
2
- export interface ApiKeyAuthMiddlewareConfig {
2
+ type StaticApiKeyConfig = {
3
+ /** The static API key to validate against */
3
4
  apiKey: string;
5
+ /** Optional header name to read the API key from. Defaults to 'x-api-key' */
4
6
  headerName?: string;
5
- }
6
- export declare function ApiKeyAuthMiddleware(config: ApiKeyAuthMiddlewareConfig): RequestHandler;
7
+ };
8
+ type CustomValidationConfig = {
9
+ /** Optional header name to read the API key from. Defaults to 'x-api-key' */
10
+ headerName?: string;
11
+ /** Custom validation function that receives the API key and returns a Promise<boolean> */
12
+ validateApiKey: (key: string) => Promise<boolean>;
13
+ };
14
+ export declare function apiKeyAuthMiddleware(config: StaticApiKeyConfig): RequestHandler;
15
+ export declare function apiKeyAuthMiddleware(config: CustomValidationConfig): RequestHandler;
16
+ export {};
@@ -3,4 +3,23 @@ import { VerifyOptions } from "jsonwebtoken";
3
3
  export interface JWTAuthMiddlewareConfig extends VerifyOptions {
4
4
  secret: string;
5
5
  }
6
- export declare function JWTAuthMiddleware(config: JWTAuthMiddlewareConfig): RequestHandler;
6
+ /**
7
+ * Middleware to authenticate requests using a JWT.
8
+ * @param config - Configuration object containing the JWT secret and verify options.
9
+ * @returns Express middleware function.
10
+ *
11
+ * @example
12
+ * ```ts
13
+ * const middleware = jwtAuthMiddleware({
14
+ * secret: process.env.JWT_SECRET!,
15
+ * algorithms: ["HS256"],
16
+ * issuer: "https://example.com",
17
+ * audience: "https://example.com",
18
+ * subject: "user-id",
19
+ * expiresIn: "1h",
20
+ * notBefore: "1h",
21
+ * clockTolerance: 30,
22
+ * });
23
+ * ```
24
+ */
25
+ export declare function jwtAuthMiddleware(config: JWTAuthMiddlewareConfig): RequestHandler;
@@ -0,0 +1,12 @@
1
+ import { RequestHandler } from "express";
2
+ import { ProxyOAuthServerProvider } from "./providers/proxy-provider";
3
+ import { OAuthProxyConfig } from "./types";
4
+ export interface OAuthProxy {
5
+ provider: ProxyOAuthServerProvider;
6
+ router: RequestHandler;
7
+ middleware: RequestHandler;
8
+ }
9
+ /**
10
+ * Creates an OAuth proxy setup
11
+ */
12
+ export declare function createOAuthProxy(config: OAuthProxyConfig): OAuthProxy;
@@ -0,0 +1,5 @@
1
+ export * from "./types";
2
+ export * from "./storage/memory-storage";
3
+ export { ProxyOAuthServerProvider } from "./providers/proxy-provider";
4
+ export { createOAuthRouter, createOAuthMiddleware } from "./router";
5
+ export { createOAuthProxy } from "./factory";
@@ -0,0 +1,13 @@
1
+ import { ProxyOAuthServerProvider as IProxyOAuthServerProvider, ProxyOAuthProviderConfig, AccessToken, AuthorizeParams, TokenParams, RevokeParams, TokenResponse } from "../types";
2
+ export declare class ProxyOAuthServerProvider implements IProxyOAuthServerProvider {
3
+ private config;
4
+ private storage;
5
+ constructor(config: ProxyOAuthProviderConfig);
6
+ get endpoints(): import("../types").OAuthEndpoints;
7
+ verifyAccessToken(token: string): Promise<AccessToken>;
8
+ authorize(params: AuthorizeParams): Promise<string>;
9
+ token(params: TokenParams): Promise<TokenResponse>;
10
+ revoke(params: RevokeParams): Promise<void>;
11
+ private verifyTokenWithProvider;
12
+ private createOAuthError;
13
+ }
@@ -0,0 +1,4 @@
1
+ import { Router, Request, Response, NextFunction } from "express";
2
+ import { OAuthRouterConfig } from "./types";
3
+ export declare function createOAuthRouter(config: OAuthRouterConfig): Router;
4
+ export declare function createOAuthMiddleware(provider: any): (req: Request, res: Response, next: NextFunction) => Promise<void>;
@@ -0,0 +1,12 @@
1
+ import { OAuthStorage, TokenStorage, AccessToken } from "../types";
2
+ export declare class MemoryTokenStorage implements TokenStorage {
3
+ tokens: Map<string, AccessToken>;
4
+ getToken(token: string): Promise<AccessToken | null>;
5
+ saveToken(token: AccessToken): Promise<void>;
6
+ deleteToken(token: string): Promise<void>;
7
+ deleteTokensByClient(clientId: string): Promise<void>;
8
+ }
9
+ export declare class MemoryOAuthStorage implements OAuthStorage {
10
+ tokens: TokenStorage;
11
+ constructor();
12
+ }
@@ -0,0 +1,112 @@
1
+ export interface OAuthClient {
2
+ client_id: string;
3
+ client_secret?: string;
4
+ redirect_uris: string[];
5
+ grant_types?: string[];
6
+ response_types?: string[];
7
+ scopes?: string[];
8
+ }
9
+ export interface AccessToken {
10
+ token: string;
11
+ clientId: string;
12
+ scopes: string[];
13
+ expiresAt?: Date;
14
+ refreshToken?: string;
15
+ }
16
+ export interface OAuthEndpoints {
17
+ authorizationUrl: string;
18
+ tokenUrl: string;
19
+ revocationUrl?: string;
20
+ userInfoUrl?: string;
21
+ registerUrl: string;
22
+ }
23
+ export interface OAuthError {
24
+ error: string;
25
+ error_description?: string;
26
+ error_uri?: string;
27
+ }
28
+ export interface TokenResponse {
29
+ access_token: string;
30
+ token_type: string;
31
+ expires_in?: number;
32
+ refresh_token?: string;
33
+ scope?: string;
34
+ }
35
+ export interface OAuthStorage {
36
+ tokens: TokenStorage;
37
+ }
38
+ export interface TokenStorage {
39
+ getToken(token: string): Promise<AccessToken | null>;
40
+ saveToken(token: AccessToken): Promise<void>;
41
+ deleteToken(token: string): Promise<void>;
42
+ deleteTokensByClient(clientId: string): Promise<void>;
43
+ }
44
+ export interface ProxyOAuthProviderConfig {
45
+ endpoints: OAuthEndpoints;
46
+ storage?: OAuthStorage;
47
+ verifyAccessToken?: (token: string) => Promise<AccessToken>;
48
+ issuerUrl?: string;
49
+ defaultScopes?: string[];
50
+ }
51
+ export interface OAuthRouterConfig {
52
+ provider: ProxyOAuthServerProvider;
53
+ issuerUrl: URL;
54
+ baseUrl: URL;
55
+ serviceDocumentationUrl?: URL;
56
+ pathPrefix?: string;
57
+ }
58
+ export interface ProxyOAuthServerProvider {
59
+ verifyAccessToken(token: string): Promise<AccessToken>;
60
+ authorize(params: AuthorizeParams): Promise<string>;
61
+ token(params: TokenParams): Promise<TokenResponse>;
62
+ revoke(params: RevokeParams): Promise<void>;
63
+ readonly endpoints: OAuthEndpoints;
64
+ }
65
+ export interface AuthorizeParams {
66
+ response_type: string;
67
+ client_id: string;
68
+ redirect_uri: string;
69
+ scope?: string;
70
+ state?: string;
71
+ code_challenge: string;
72
+ code_challenge_method: string;
73
+ }
74
+ export interface TokenParams {
75
+ grant_type: string;
76
+ client_id: string;
77
+ client_secret?: string;
78
+ code?: string;
79
+ redirect_uri?: string;
80
+ refresh_token?: string;
81
+ code_verifier?: string;
82
+ }
83
+ export interface RevokeParams {
84
+ token: string;
85
+ token_type_hint?: string;
86
+ client_id?: string;
87
+ client_secret?: string;
88
+ }
89
+ export interface OAuthConfigOptions {
90
+ endpoints: {
91
+ authorizationUrl: string;
92
+ tokenUrl: string;
93
+ revocationUrl?: string;
94
+ userInfoUrl?: string;
95
+ registerUrl: string;
96
+ };
97
+ issuerUrl: string;
98
+ baseUrl: string;
99
+ serviceDocumentationUrl?: string;
100
+ pathPrefix?: string;
101
+ defaultScopes?: string[];
102
+ }
103
+ export interface OAuthProxyConfig {
104
+ endpoints: OAuthEndpoints;
105
+ issuerUrl: string;
106
+ baseUrl: string;
107
+ serviceDocumentationUrl?: string;
108
+ pathPrefix?: string;
109
+ storage?: OAuthStorage;
110
+ verifyAccessToken?: (token: string) => Promise<any>;
111
+ defaultScopes?: string[];
112
+ }