mcp-server-plus

소개

mcp-server-plus는 MCP 서버 툴킷입니다. 반복적인 보일러플레이트 없이 Model Context Protocol 서버를 구축하기 위한 작은 TypeScript 프레임워크입니다.

패키지 이름 참고: mcp-server-toolkit은 이미 npm에 등록되어 있어서, 이 패키지는 mcp-server-plus 로 배포됩니다.

Related MCP server: MCP Framework

이 패키지가 존재하는 이유

MCP 서버를 시작하는 개발자들은 도구 등록, 프롬프트, 리소스, 인증, 로깅, 테스트를 반복적으로 재구현합니다. Express나 Hono 같은 인기 있는 라이브러리는 행복한 경로를 명확하게 만들어 주기 때문에 성공합니다. mcp-server-plus는 공식 @modelcontextprotocol/sdk 위에서 동일한 개발자 경험을 목표로 합니다.

설치

npm install mcp-server-plus zod

Node.js 18+가 필요합니다.

기능

• 도구 등록

• 프롬프트 레지스트리

• 리소스

• 인증 / 권한 부여

• 로깅

• 메트릭

• 스트리밍 (MCP stdio 전송 방식)

• 미들웨어

• CLI 스캐폴더

• 테스트 헬퍼

빠른 시작

import { z } from "zod";
import { createServer, toolResult } from "mcp-server-plus";

const weatherTool = {
  description: "Get weather",
  inputSchema: { city: z.string() },
  async handler({ city }: { city: string }) {
    return toolResult(`Weather in ${city}: sunny`);
  },
};

const server = createServer({
  name: "demo",
  version: "1.0.0",
});

server.tool("weather", weatherTool);

await server.start(); // stdio

CLI

npx mcp-server-plus init my-weather-server
cd my-weather-server
npm install
npm start

API 참조

createServer(options) / createMcpServer(options)

McpKitServer를 생성합니다.

server.tool(name, definition)

도구를 등록합니다 (MCP SDK에도 연결됨).

server.prompt(name, definition)

프롬프트 템플릿을 등록합니다.

server.resource(uri, definition)

리소스를 등록합니다.

server.use(middleware)

도구 호출 주위에 미들웨어를 추가합니다.

server.start()

MCP stdio 전송 방식을 연결합니다 (스트리밍은 SDK가 처리).

server.invokeTool(name, args, meta?)

테스트/스크립트용 프로세스 내 호출.

테스트 헬퍼

import { callTool, expectText } from "mcp-server-plus/testing";

예제

server.tool("weather", weatherTool);
server.prompt("greet", {
  description: "Greeting",
  arguments: [{ name: "name", required: true }],
  handler: async ({ name }) => ({
    messages: [
      { role: "user", content: { type: "text", text: `Hello ${name}` } },
    ],
  }),
});
server.resource("memo://hello", {
  mimeType: "text/plain",
  handler: async (uri) => ({
    contents: [{ uri: uri.href, text: "Hello", mimeType: "text/plain" }],
  }),
});

고급 예제

인증 + RBAC

const server = createServer({
  name: "secure",
  version: "1.0.0",
  // MCP_API_KEY is the expected secret only. Callers must still send meta.apiKey.
  auth: { apiKey: process.env.MCP_API_KEY, required: true },
});

server.tool("deploy", {
  roles: ["admin"],
  scopes: ["deploy"],
  handler: async () => toolResult("deployed"),
});

미들웨어 + 메트릭

server.use(async (ctx, next) => {
  const started = Date.now();
  try {
    return await next();
  } finally {
    ctx.log.info("tool timing", ctx.toolName, Date.now() - started);
  }
});

console.log(server.metricsSnapshot());

프레임워크 통합

stdio 서버를 지원하는 모든 MCP 호스트와 함께 작동합니다. 호스트를 node dist/index.js (또는 npm start) 프로세스로 지정하세요.

MCP 호스트 구성 예시:

{
  "mcpServers": {
    "demo": {
      "command": "node",
      "args": ["/path/to/server/src/index.js"]
    }
  }
}

TypeScript 사용

일류 TypeScript 지원. 핸들러를 명시적으로 타입 지정하면 도구 인수가 Zod inputSchema에서 추론됩니다. 최상의 결과를 위해 strict를 활성화하세요.

오류 처리

타입화된 오류: McpKitError, AuthError, ForbiddenError.
도구 실패는 { isError: true, content: [...] }를 반환하므로 호스트가 안전하게 표시할 수 있습니다.

성능

• 공식 SDK 위의 얇은 래퍼 (추가 네트워크 홉 없음)

• 미들웨어는 도구 호출에만 적용

• 메트릭은 간단한 카운터 사용 (낮은 오버헤드)

모범 사례

• 도구를 작고 부작용에 민감하게 유지

• Zod 스키마로 입력 검증

• 로컬/개발에는 optional 인증, 공유 호스트에는 required 사용

• 단위 테스트에서는 invokeTool 선호, 통합 테스트에서는 stdio 사용

FAQ

공식 SDK인가요?
아니요 — @modelcontextprotocol/sdk 위에 더 나은 개발자 경험을 제공합니다.

스트리밍을 지원하나요?
예, server.start()에서 사용하는 MCP stdio 전송 방식을 통해 지원합니다.

CJS 또는 ESM?
이중 게시, ESM 우선.

마이그레이션 가이드

원시 SDK McpServer에서

registerTool 보일러플레이트를 server.tool(name, definition)으로 대체하고 Zod 스키마는 유지하세요. StdioServerTransport를 수동으로 연결하는 대신 server.start()를 호출하세요.

SemVer

주요 변경 사항은 메이저 버전에 포함되며 CHANGELOG.md에 문서화됩니다.

문제 해결

기여

CONTRIBUTING.md를 참조하세요.

라이선스

MIT