mcpkit
mcpkit
ボイラープレートなしでMCPサーバーを構築するためのTypeScriptツールキット。
Zodスキーマとハンドラーを使ってツールを定義するだけ。スキーマ生成、入力バリデーション、エラーエンベロープ、トランスポートの配線など、すべてが完了したModel Context Protocolサーバーが手に入ります。
import { defineServer, defineTool } from 'mcpkit';
import { z } from 'zod';
const server = defineServer({
name: 'demo',
version: '0.1.0',
tools: [
defineTool({
name: 'add',
description: 'Add two numbers.',
input: z.object({ a: z.number(), b: z.number() }),
handler: ({ a, b }) => `${a + b}`,
}),
],
});
await server.start();これは、実用的で機能するMCPサーバーです。mcpkit devで実行し、MCP対応クライアントを接続してください。
なぜこれが存在するのか
公式SDKでMCPサーバーを書くことは可能ですが、毎回同じような配線作業が必要になります:
ツールリストを1箇所で宣言する
各ツールに対して個別のJSONスキーマを宣言する
呼び出しハンドラー内でツール名によるswitch文を書く
ハンドラーの戻り値をプロトコルのコンテンツエンベロープに変換する
トランスポートを配線する
エラーをキャッチして適切な
isError形式に変換する
mcpkitは、これらすべてをdefineTool + defineServerに集約します。スキーマはZod型から生成され、バリデーションはハンドラーの前に実行され、エラーは適切なプロトコルレスポンスに変換され、文字列の戻り値はテキストコンテンツブロックになります。あなたは実際に重要なレイヤー(ツールが何をするか)に集中し、重要でないレイヤーをスキップできます。
Related MCP server: MCP Base Server
比較:なし vs あり
同じツールを、生のSDKで書いた場合とmcpkitで書いた場合の比較:
const server = new Server(
{ name: 'demo', version: '0.1.0' },
{ capabilities: { tools: {} } },
);
server.setRequestHandler(
ListToolsRequestSchema,
async () => ({
tools: [
{
name: 'add',
description: 'Add two numbers.',
inputSchema: {
type: 'object',
properties: {
a: { type: 'number' },
b: { type: 'number' },
},
required: ['a', 'b'],
},
},
],
}),
);
server.setRequestHandler(
CallToolRequestSchema,
async (req) => {
if (req.params.name === 'add') {
const { a, b } = req.params.arguments as {
a: number; b: number;
};
return {
content: [{ type: 'text', text: `${a + b}` }],
};
}
throw new Error('unknown tool');
},
);
await server.connect(new StdioServerTransport());const server = defineServer({
name: 'demo',
version: '0.1.0',
tools: [
defineTool({
name: 'add',
description: 'Add two numbers.',
input: z.object({
a: z.number(),
b: z.number(),
}),
handler: ({ a, b }) => `${a + b}`,
}),
],
});
await server.start();右側の列は、同じワイヤーレベルの動作に加え、入力バリデーション、型安全なハンドラー引数、キャッチされない例外に対するisErrorエンベロープを備えています。
インストール
npm install mcpkit zodまたは、新規プロジェクトをスキャフォールドします(最初のサーバー作成にはこちらを推奨):
npx mcpkit create my-server
cd my-server
npm run devstdioサーバー、3つのサンプルツール、厳格モードに設定されたtsconfig.jsonを含む小さなプロジェクトが作成されます。サンプルツールを自分のツールに置き換えてリリースしてください。
CLI
mcpkit create [target] scaffold a new server from a template
mcpkit dev run with hot reload (uses tsx under the hood)
mcpkit build compile to dist/
mcpkit inspect launch the official inspector against your servercreateコマンドは現在4つのテンプレートを提供しています:
テンプレート | 内容 |
| stdio経由のローカルMCPサーバー。ほとんどのクライアントがこれを使用します。 |
| ストリーム可能なHTTPトランスポート経由のネットワーク到達可能なサーバー。 |
| HTTPフェッチツールを備えたstdioサーバー(タイムアウト設定済み)。 |
| SQLiteバックエンドのCRUD例を備えたstdioサーバー(better-sqlite3, WAL)。 |
API
defineTool
defineTool({
name: string, // [a-zA-Z0-9_-]+
description: string, // shown to the client / LLM
input: z.ZodType, // Zod schema; converted to JSON Schema for you
handler: (input) => string | ToolContent | ToolContent[] | { content, isError? }
})ハンドラーの入力はz.inferを通じて完全に型付けされます。文字列を返すと、単一のテキストコンテンツブロックとしてラップされます(一般的なケース)。ハンドラー内で例外を投げると、自動的にisError: trueレスポンスに変換されます。エラーメッセージをカスタマイズしたい場合は、defineServerにonToolErrorハンドラーを渡してください。
defineServer
defineServer({
name: string,
version: string,
description?: string,
tools?: ToolDefinition[],
resources?: ResourceDefinition[],
prompts?: PromptDefinition[],
onToolError?: (err, toolName) => ToolResult,
onEvent?: (event: ServerEvent) => void,
})DefinedServerを返し、以下のメソッドを提供します:
.start({ transport: 'stdio' })— トランスポートを接続してサーバーを起動します。.connect(transport)— 自分で構築したトランスポートインスタンス(HTTP、カスタム、Transportのように振る舞うものなら何でも)を接続します。.stop()— アクティブなトランスポートと基盤となるサーバーを閉じます。.raw— 特殊な操作が必要な場合の、基盤となるSDKのServerインスタンス。
リソースとプロンプト
宣言的な形式は同じです:
defineResource({
uri: 'file:///etc/hosts',
name: 'hosts',
mimeType: 'text/plain',
read: async () => ({ text: await fs.readFile('/etc/hosts', 'utf8') }),
});
definePrompt({
name: 'summarize',
description: 'Summarize a chunk of text.',
arguments: z.object({ text: z.string() }),
build: ({ text }) => ({
messages: [{ role: 'user', content: { type: 'text', text: `Summarize:\n${text}` } }],
}),
});可観測性
onEventは、ツール呼び出し、リソース読み取り、プロンプト取得のすべてに対して構造化されたコールバックを受け取ります。開始時間、終了時間、レイテンシ、エラー、呼び出しごとのrequestIdが含まれます。pino、console、OpenTelemetry、自作の集約ツールなど、何にでも接続できます。シンプルなケース向けに組み込み機能もあります:
import { defineServer, consoleLogger, jsonLogger } from 'mcpkit';
const server = defineServer({
name: 'demo',
version: '0.1.0',
onEvent: consoleLogger(), // → pretty stderr lines
// or: onEvent: jsonLogger() // → one JSON object per line, on stderr
tools: [...]
});ログは常にstderrに出力されます。stdoutはstdioトランスポートのプロトコル通信用に予約されています。
テスト
mcpkit/testingは、メモリ内トランスポートを介してサーバーと通信するプロセス内クライアントを公開します。サブプロセスもstdioパイプも、不安定なプロセス終了もありません。実際のコンシューマーが使用するのと同じクライアントを、RAM経由でルーティングするだけです。
import { describe, it, expect } from 'vitest';
import { createTestClient, expectToolError, snapshotTools } from 'mcpkit/testing';
import { server } from '../src/index.js';
describe('add', () => {
it('adds', async () => {
const client = await createTestClient(server);
const result = await client.callTool('add', { a: 2, b: 3 });
expect(result.text).toBe('5');
expect(result.isError).toBe(false);
await client.close();
});
it('rejects bad input', async () => {
const client = await createTestClient(server);
const text = await expectToolError(client, 'add', { a: 'nope', b: 1 });
expect(text).toMatch(/invalid/i);
await client.close();
});
it("doesn't drift its public surface", () => {
expect(snapshotTools(server)).toMatchSnapshot();
});
});知っておくべき設計上の選択
生のJSONスキーマではなく、Zodを使用。 型を一度書くだけで済みます。バリデーション、プロトコル用の生成済みJSONスキーマ、ハンドラー用のTypeScript推論がすべて同じソースから得られます。3つの定義を同期させ続けることこそが、このプロジェクトが排除しようとしているボイラープレートです。
エラーは例外ではなく値。 ハンドラーが例外を投げると、isError: trueのコンテンツエンベロープになります。クライアントはトランスポートレベルの失敗ではなく、意味のあるレスポンスを受け取ります。エラーを自分でフォーマットしたい場合は、onToolErrorをオーバーライドしてください。
トランスポートに依存しないコア。 同じdefineServerがstdio、ストリーム可能なHTTPトランスポート、メモリ内テストトランスポート、その他SDKのTransportインターフェースを実装するあらゆるものの上で動作します。http-streamingテンプレートがその配線方法を示しています。
デフォルトで厳格モード。 テンプレートはstrict: trueおよびnoUncheckedIndexedAccessで提供されます。ライブラリ自体も同じ設定でコンパイルされます。型に穴を見つけた場合は、それはバグです。
リスナーエラーは飲み込まれる。 onEventハンドラーが例外を投げても、ツール呼び出しは動作し続けます。可観測性のバグが負荷を支えるべきではありません。
FAQ
mcpkitに永遠にロックインされますか?
いいえ。すべてのヘルパーには脱出ハッチがあります。server.rawで基盤となるSDKのServerにアクセスでき、キットがまだモデル化していない機能が必要な場合は、直接setRequestHandlerを呼び出すことができます。このキットは上位レイヤーであり、代替品ではありません。
なぜZod 4ではなくZod 3なのですか?
Zod 4は素晴らしいですが、エコシステム(特にzod-to-json-schema)がまだ追いついていません。本番環境で安定したら移行する予定です。すでにZod 4を使用している場合、スキーマインターフェースは十分に互換性があります。問題が発生した場合はIssueを報告してください。
ツールだけでなく、リソースやプロンプトもサポートしていますか?
はい。defineResourceとdefinePromptはファーストクラスです。ツールほど頻繁には使用されないため、ほとんどの例ではツールを前面に出していますが、配線は同一です。
ストリーム可能なHTTP、SSE、両方ですか?
ストリーム可能なHTTPです。古いHTTP+SSE形式はSDKに残っていますが、段階的に廃止されています。それが必要な理由がある場合は、defineServerはトランスポートに依存しないため、.connect()経由で任意のTransportインスタンスを渡すことができます。
本番環境で使用できますか? ライブラリは小さく、表面積は意図的に狭く設計されています。公式SDKが基盤の重い処理を行っています。バージョンを固定し、ツールのテストを書き(プロセス内クライアントがこれを容易にします)、準備完了です。
これではないもの
ホスト型サービスではありません。自分でビルドし、デプロイします。
エージェントフレームワークではありません。MCPのサーバー側を構築するものであり、クライアントではありません。
ドメインに関する意見を持ちません。ツールは関数であり、それが何をするかはあなたの問題です。
ロードマップ
さらなるテンプレート(OAuth保護、エッジランタイム、Drizzle/Postgres)。
lint + パッケージ化 + リリースタグ付けを行う
mcpkit publishコマンド。よりリッチなテストヘルパー(ツールの入力のファジング、ベースラインに対するスキーマ差分)。
onEvent用のオプションのOpenTelemetryアダプター。
不足しているものがあれば、Issueを開いて希望するAPIのスケッチを提示してください。
ライセンス
MIT。
This server cannot be installed
Maintenance
Resources
Unclaimed servers have limited discoverability.
Looking for Admin?
If you are the server author, to access and configure the admin panel.
Related MCP Servers
AlicenseCqualityDmaintenanceA lightweight and extendable MCP server toolkit that allows developers to build and integrate custom tools with AI assistants through automatic tool discovery from local directories or npm packages.218MIT- AlicenseNot gradedqualityDmaintenanceA TypeScript-based template for rapidly developing MCP servers with modular tool architecture, built-in validation using Zod schemas, and comprehensive error handling.9MIT
- FlicenseNot gradedqualityDmaintenanceA minimal MCP server framework that enables zero-config tool discovery and streamable HTTP transport using the LeanMCP SDK. It allows developers to build type-safe services with automatic schema validation and integrated React UI components.
- AlicenseBqualityDmaintenanceA TypeScript-based boilerplate for building Model Context Protocol (MCP) servers using the official SDK and Zod. It provides a structured foundation with a decoupled architecture to simplify the creation and registration of custom MCP tools.116ISC
Related MCP Connectors
Markdown-first MCP server for Notion API with 8 composite tools and 39 actions.
MCP server for Clipkit — gives AI agents a video toolbox via the Clipkit schema.
MCP server for secureFlows: token-free URL builders and integration-linting tools for AI agents.
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
MCP directory API
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/EuKennedy/mcpkit'
If you have feedback or need assistance with the MCP directory API, please join our Discord server