xmcp boilerplate

xmcp Application

This project was created with create-xmcp-app.

Getting Started

First, run the development server:

1
npm run dev
2
# or
3
yarn dev
4
# or
5
pnpm dev

This will start the MCP server with the selected transport method.

Project Structure

This project uses the structured approach where tools, prompts, and resources are automatically discovered from their respective directories:

• src/tools - Tool definitions
• src/prompts - Prompt templates
• src/resources - Resource handlers

Tools

Each tool is defined in its own file with the following structure:

1
import { z } from 'zod'
2
import { type InferSchema, type ToolMetadata } from 'xmcp'
3

4
export const schema = {
5
  name: z.string().describe('The name of the user to greet'),
6
}
7

8
export const metadata: ToolMetadata = {
9
  name: 'greet',
10
  description: 'Greet the user',
11
  annotations: {
12
    title: 'Greet the user',
13
    readOnlyHint: true,
14
    destructiveHint: false,
15
    idempotentHint: true,
16
  },
17
}
18

19
export default function greet({ name }: InferSchema<typeof schema>) {
20
  return `Hello, ${name}!`
21
}

Prompts

Prompts are template definitions for AI interactions:

1
import { z } from 'zod'
2
import { type InferSchema, type PromptMetadata } from 'xmcp'
3

4
export const schema = {
5
  code: z.string().describe('The code to review'),
6
}
7

8
export const metadata: PromptMetadata = {
9
  name: 'review-code',
10
  title: 'Review Code',
11
  description: 'Review code for best practices and potential issues',
12
  role: 'user',
13
}
14

15
export default function reviewCode({ code }: InferSchema<typeof schema>) {
16
  return `Please review this code: ${code}`
17
}

Resources

Resources provide data or content with URI-based access:

1
import { z } from 'zod'
2
import { type ResourceMetadata, type InferSchema } from 'xmcp'
3

4
export const schema = {
5
  userId: z.string().describe('The ID of the user'),
6
}
7

8
export const metadata: ResourceMetadata = {
9
  name: 'user-profile',
10
  title: 'User Profile',
11
  description: 'User profile information',
12
}
13

14
export default function handler({ userId }: InferSchema<typeof schema>) {
15
  return `Profile data for user ${userId}`
16
}

Adding New Components

Adding New Tools

To add a new tool:

1. Create a new .ts file in the src/tools directory
2. Export a schema object defining the tool parameters using Zod
3. Export a metadata object with tool information
4. Export a default function that implements the tool logic

Adding New Prompts

To add a new prompt:

1. Create a new .ts file in the src/prompts directory
2. Export a schema object defining the prompt parameters using Zod
3. Export a metadata object with prompt information and role
4. Export a default function that returns the prompt text

Adding New Resources

To add a new resource:

1. Create a new .ts file in the src/resources directory
2. Use folder structure to define the URI (e.g., (users)/[userId]/profile.ts → users://{userId}/profile)
3. Export a schema object for dynamic parameters (optional for static resources)
4. Export a metadata object with resource information
5. Export a default function that returns the resource content

Building for Production

To build your project for production:

1
pnpm build

This will compile your TypeScript code and output it to the dist directory.

Running the Server

You can run the server for the transport built with:

• HTTP: node dist/http.js
• STDIO: node dist/stdio.js

Given the selected transport method, you will have a custom start script added to the package.json file.

For HTTP:

1
pnpm start-http

For STDIO:

1
pnpm start-stdio

Learn More

• xmcp Documentation