xmcp 0.0.16 → 0.0.17-alpha.2

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 -225
  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 +19 -8
  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,238 +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 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
- - 🔍 **File system routing** - Tools are automatically discovered and registered from `src/tools` directory.
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
- - 📡 **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
22
-
23
- ## Quick Start
24
-
25
- The fastest way to get started is with the project generator:
26
-
27
- ```bash
28
- npx create-xmcp-app my-mcp-server
29
- cd my-mcp-server
30
- npm run dev
31
- ```
32
-
33
- ## Project structure
34
-
35
- A basic project structure is as follows:
36
-
37
- ```
38
- my-project/
39
- ├── src/
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
- ├── package.json
46
- ├── tsconfig.json
47
- └── xmcp.config.ts # Configuration file for xmcp
48
- ```
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:
55
-
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
- };
91
- }
92
- ```
93
-
94
- ## Tool file structure
95
-
96
- ### 1. Schema (Required)
97
-
98
- ```typescript
99
- import { z } from "zod";
100
-
101
- export const schema = {
102
- a: z.number().describe("First number to add"),
103
- b: z.number().describe("Second number to add"),
104
- };
105
- ```
106
-
107
- The schema object defines the tool's parameters with:
108
-
109
- - **Key**: Parameter name
110
- - **Value**: Zod schema with `.describe()` for documentation. This will be visibile through the inspector.
111
- - **Purpose**: Type validation and automatic parameter documentation.
112
-
113
- ### 2. Metadata (Required)
114
-
115
- Define the tool's identity and behavior hints:
116
-
117
- ```typescript
118
- export const metadata = {
119
- name: "add",
120
- description: "Add two numbers together",
121
- annotations: {
122
- title: "Add Two Numbers", // Human-readable display name
123
- readOnlyHint: true, // true = doesn't modify external state
124
- destructiveHint: false, // true = performs destructive operations
125
- idempotentHint: true, // true = same inputs = same outputs
126
- },
127
- };
128
- ```
16
+ ## The TypeScript MCP Framework
129
17
 
130
- 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.
131
19
 
132
- - **name**: Unique identifier for the tool
133
- - **description**: Brief explanation of what the tool does
134
- - **annotations**: Behavioral hints for AI models and UIs
135
-
136
- This extends entirely from the MCP library.
137
-
138
- ### 3. Implementation (Required)
139
-
140
- The default export function that performs the actual work:
141
-
142
- ```typescript
143
- import { type InferSchema } from "xmcp";
144
-
145
- export default async function add({ a, b }: InferSchema<typeof schema>) {
146
- return {
147
- content: [{ type: "text", text: String(a + b) }],
148
- };
149
- }
150
- ```
151
-
152
- The implementation function:
153
-
154
- - **Parameters**: Automatically typed from your schema using the built-in `InferSchema`
155
- - **Return**: MCP-compatible response with content array
156
- - **Async**: Supports async operations for API calls, file I/O, etc.
157
-
158
- ## Development Commands
159
-
160
- ```bash
161
- # Start development server with hot reloading
162
- npm run dev
163
-
164
- # Build for production
165
- npm run build
166
-
167
- # Start built server (stdio transport)
168
- node dist/stdio.js
169
-
170
- # Start built server (HTTP transport)
171
- node dist/http.js
172
- ```
173
-
174
- ## Key Concepts
175
-
176
- ### Tool Discovery
177
-
178
- - Tools are automatically discovered from the `src/tools/` directory
179
- - Each `.ts` file becomes a tool
180
- - No manual registration required
181
-
182
- ### Type Safety
183
-
184
- - `InferSchema<typeof schema>` provides full TypeScript type inference
185
- - Parameters are automatically validated against your Zod schemas
186
- - Compile-time type checking for tool implementations
187
-
188
- ### MCP Compatibility
189
-
190
- - Tools return MCP-compatible response objects
191
- - Supports both `stdio` and `http` transports
192
- - Full compatibility with MCP clients and AI models
193
-
194
- ## Vercel Deployment
195
-
196
- XMCP can be deployed to Vercel with the `--vercel` flag. This will create `.vercel` directory with the built output.
197
-
198
- ```bash
199
- xmcp build --vercel
200
- ```
201
-
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";
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.
210
21
 
211
- export const middleware: Middleware = async (req, next) => {
212
- const headers = headers();
213
- const accept = headers["accept"];
214
- return next();
215
- };
216
- ```
22
+ ## Getting Started
217
23
 
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.
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.
219
26
 
220
- ## xmcp/headers
27
+ ## Features
221
28
 
222
- If you are building an `http` mcp server, you can access the request headers using the `xmcp/headers` module.
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
223
40
 
224
- ```typescript
225
- import { headers } from "xmcp/headers";
41
+ ## Security
226
42
 
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
- ```
43
+ If you believe you have found a security vulnerability, we encourage you to let us know right away.
235
44
 
236
- ---
45
+ We will investigate all legitimate reports and do our best to quickly fix the problem.
237
46
 
238
- From the [basement.studio](https://basement.studio)
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
+ }