mcpkit
mcpkit
상용구 코드 없이 MCP 서버를 구축하기 위한 TypeScript 툴킷입니다.
Zod 스키마와 핸들러로 도구를 정의하세요. 작동하는 Model Context Protocol 서버를 바로 얻을 수 있습니다. 스키마 생성, 입력 유효성 검사, 오류 봉투(error envelopes), 전송 연결까지 모두 처리됩니다.
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 서버를 작성하는 것도 괜찮지만, 매번 똑같은 배관 작업을 반복하게 됩니다:
도구 목록을 한 곳에 선언
각 도구에 대해 별도의 JSON 스키마 선언
호출 핸들러에서 도구 이름에 따른 switch 문 작성
핸들러 반환값을 프로토콜의 콘텐츠 봉투로 강제 변환
전송(transport) 연결
오류를 포착하여 올바른
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 dev작동하는 stdio 서버, 세 가지 예제 도구, 엄격 모드로 설정된 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는 현재 네 가지 템플릿을 제공합니다:
템플릿 | 제공 내용 |
| 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— 특수한 작업이 필요한 경우 기본 SDKServer에 접근합니다.
리소스 및 프롬프트
동일한 선언적 형태를 가집니다:
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}` } }],
}),
});관측 가능성(Observability)
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 추론이 모두 동일한 소스에서 나옵니다. 세 가지 정의를 동기화 상태로 유지하려는 노력이 바로 이 프로젝트가 제거하고자 하는 상용구 코드입니다.
오류는 예외가 아닌 값입니다. 예외를 던지는 핸들러는 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를 사용 중이라면 스키마 인터페이스는 충분히 호환됩니다. 문제가 발생하면 이슈를 제기해 주세요.
도구뿐만 아니라 리소스와 프롬프트도 지원하나요?
네. defineResource와 definePrompt는 일급 객체입니다. 도구보다 덜 자주 사용되므로 대부분의 예제는 도구로 시작하지만, 연결 방식은 동일합니다.
스트리밍 HTTP, SSE, 둘 다 지원하나요?
스트리밍 HTTP를 지원합니다. 이전의 HTTP+SSE 방식은 여전히 SDK에 있지만 단계적으로 폐지되고 있습니다. 만약 꼭 필요하다면 defineServer는 전송 방식에 구애받지 않으므로 .connect()를 통해 어떤 Transport 인스턴스든 전달할 수 있습니다.
프로덕션 준비가 되었나요? 라이브러리는 작고 의도적으로 좁은 범위를 다룹니다. 공식 SDK가 내부적으로 무거운 작업을 처리합니다. 버전을 고정하고 도구에 대한 테스트를 작성하면(프로세스 내 클라이언트로 쉽게 가능) 준비가 완료된 것입니다.
이 프로젝트가 아닌 것
호스팅 서비스가 아닙니다. 직접 빌드하고 배포하세요.
에이전트 프레임워크가 아닙니다. MCP의 서버 측을 구축하는 도구이며 클라이언트가 아닙니다.
도메인에 대해 독단적이지 않습니다. 도구는 함수일 뿐이며, 그 함수가 무엇을 하는지는 여러분의 몫입니다.
로드맵
더 많은 템플릿 (OAuth 보호, 엣지 런타임, Drizzle/Postgres).
린트 + 패키징 + 릴리스 태그 지정을 수행하는
mcpkit publish명령어.더 풍부한 테스트 헬퍼 (도구 입력 퍼징, 기준 대비 스키마 차이 비교).
onEvent를 위한 선택적 OpenTelemetry 어댑터.
빠진 기능이 있다면 원하는 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