MCP 프레임워크
MCP(Model Context Protocol) 서버를 구축하기 위한 TypeScript 프레임워크입니다.
원본과의 변경 사항
이 포크(@ronangrant/mcp-framework)에는 다음과 같은 개선 사항이 포함되어 있습니다.
- 더 나은 호환성과 안정성을 위해 파일 기반 로깅을 콘솔 전용 로깅으로 교체했습니다.
- 로그에 대한 파일 시스템 종속성을 제거하여 ENOENT 오류를 제거했습니다.
- 동일한 인터페이스를 유지하면서 로깅 구현을 간소화했습니다.
- 이제 모든 로그가 console.error()를 통해 stderr로 출력됩니다.
설치
지엑스피1
용법
새로운 MCP 서버를 만듭니다.
import { MCPServer } from '@ronangrant/mcp-framework';
const server = new MCPServer({
name: "my-server",
version: "1.0.0"
});
await server.start();
특징
- MCP 서버 생성을 위한 사용하기 쉬운 API
- 도구, 프롬프트 및 리소스에 대한 기본 지원
- 콘솔 출력을 통한 간소화된 로깅 시스템
- 전체 TypeScript 지원
- 유연한 운송 옵션
특허
MIT
MCP-Framework은 TypeScript에서 Model Context Protocol(MCP) 서버를 우아하게 구축하기 위한 프레임워크입니다.
MCP-Framework는 도구, 리소스 및 프롬프트에 대한 자동 디렉터리 기반 검색 기능을 통해 즉시 사용 가능한 아키텍처를 제공합니다. 강력한 MCP 추상화를 사용하여 도구, 리소스 또는 프롬프트를 세련되게 정의하세요. CLI를 사용하면 MCP 서버를 손쉽게 시작할 수 있습니다.
특징
- 🛠️ 도구, 리소스 및 프롬프트의 자동 검색 및 로딩
- 다중 전송 지원(stdio, SSE)
- 완전한 유형 안전성을 갖춘 TypeScript 우선 개발
- 공식 MCP SDK 기반으로 구축됨
- 도구, 프롬프트 및 리소스를 위한 사용하기 쉬운 기본 클래스
- SSE 엔드포인트에 대한 기본 인증
mcp-framework로 저장소 만들기
CLI 사용(권장)
# Install the framework globally
npm install -g mcp-framework
# Create a new MCP server project
mcp create my-mcp-server
# Navigate to your project
cd my-mcp-server
# Your server is ready to use!
CLI 사용법
이 프레임워크는 MCP 서버 프로젝트를 관리하기 위한 강력한 CLI를 제공합니다.
프로젝트 생성
# Create a new project
mcp create <your project name here>
도구 추가
# Add a new tool
mcp add tool price-fetcher
프롬프트 추가
# Add a new prompt
mcp add prompt price-analysis
리소스 추가
# Add a new prompt
mcp add resource market-data
개발 워크플로
- 프로젝트를 생성하세요:
mcp create my-mcp-server
cd my-mcp-server
- 필요에 따라 도구를 추가하세요:
mcp add tool data-fetcher
mcp add tool data-processor
mcp add tool report-generator
- 짓다:
- MCP 클라이언트에 추가(Claude Desktop 예제는 아래를 참조하세요)
Claude Desktop과 함께 사용
지역 개발
Claude Desktop 구성 파일에 다음 구성을 추가하세요.
MacOS : `~/라이브러리/애플리케이션 지원/클로드/클로드_데스크탑_config.json` Windows : `%APPDATA%/클로드/클로드_데스크탑_config.json`
{
"mcpServers": {
"${projectName}": {
"command": "node",
"args":["/absolute/path/to/${projectName}/dist/index.js"]
}
}
}
출판 후
Claude Desktop 구성 파일에 다음 구성을 추가하세요.
MacOS : `~/라이브러리/애플리케이션 지원/클로드/클로드_데스크탑_config.json` Windows : `%APPDATA%/클로드/클로드_데스크탑_config.json`
{
"mcpServers": {
"${projectName}": {
"command": "npx",
"args": ["${projectName}"]
}
}
}
빌딩 및 테스트
- 도구를 변경하세요
- `npm run build`를 실행하여 컴파일합니다.
- 서버는 시작 시 자동으로 도구를 로드합니다.
빠른 시작
도구 만들기
import { MCPTool } from "mcp-framework";
import { z } from "zod";
interface ExampleInput {
message: string;
}
class ExampleTool extends MCPTool<ExampleInput> {
name = "example_tool";
description = "An example tool that processes messages";
schema = {
message: {
type: z.string(),
description: "Message to process",
},
};
async execute(input: ExampleInput) {
return `Processed: ${input.message}`;
}
}
export default ExampleTool;
서버 설정
import { MCPServer } from "mcp-framework";
const server = new MCPServer();
// OR (mutually exclusive!) with SSE transport
const server = new MCPServer({
transport: {
type: "sse",
options: {
port: 8080 // Optional (default: 8080)
}
}
});
// Start the server
await server.start();
전송 구성
stdio 전송(기본값)
전송 구성이 제공되지 않으면 기본적으로 stdio 전송이 사용됩니다.
const server = new MCPServer();
// or explicitly:
const server = new MCPServer({
transport: { type: "stdio" }
});
SSE 운송
SSE(Server-Sent Events) 전송을 사용하려면:
const server = new MCPServer({
transport: {
type: "sse",
options: {
port: 8080, // Optional (default: 8080)
endpoint: "/sse", // Optional (default: "/sse")
messageEndpoint: "/messages", // Optional (default: "/messages")
cors: {
allowOrigin: "*", // Optional (default: "*")
allowMethods: "GET, POST, OPTIONS", // Optional (default: "GET, POST, OPTIONS")
allowHeaders: "Content-Type, Authorization, x-api-key", // Optional (default: "Content-Type, Authorization, x-api-key")
exposeHeaders: "Content-Type, Authorization, x-api-key", // Optional (default: "Content-Type, Authorization, x-api-key")
maxAge: "86400" // Optional (default: "86400")
}
}
}
});
CORS 구성
SSE 전송은 유연한 CORS 구성을 지원합니다. 기본적으로 개발 환경에 적합한 허용 설정을 사용합니다. 프로덕션 환경에서는 보안 요구 사항에 따라 CORS를 구성해야 합니다.
const server = new MCPServer({
transport: {
type: "sse",
options: {
// Restrict to specific origin
cors: {
allowOrigin: "https://myapp.com",
allowMethods: "GET, POST",
allowHeaders: "Content-Type, Authorization",
exposeHeaders: "Content-Type, Authorization",
maxAge: "3600"
}
}
}
});
// Or with multiple allowed origins
const server = new MCPServer({
transport: {
type: "sse",
options: {
cors: {
allowOrigin: "https://app1.com, https://app2.com",
allowMethods: "GET, POST, OPTIONS",
allowHeaders: "Content-Type, Authorization, Custom-Header",
exposeHeaders: "Content-Type, Authorization",
maxAge: "86400"
}
}
}
});
입증
MCP 프레임워크는 SSE 엔드포인트에 대한 선택적 인증을 제공합니다. JWT와 API 키 인증 중 하나를 선택하거나, 사용자 지정 인증 공급자를 직접 구현할 수 있습니다.
JWT 인증
import { MCPServer, JWTAuthProvider } from "mcp-framework";
import { Algorithm } from "jsonwebtoken";
const server = new MCPServer({
transport: {
type: "sse",
options: {
auth: {
provider: new JWTAuthProvider({
secret: process.env.JWT_SECRET,
algorithms: ["HS256" as Algorithm], // Optional (default: ["HS256"])
headerName: "Authorization" // Optional (default: "Authorization")
}),
endpoints: {
sse: true, // Protect SSE endpoint (default: false)
messages: true // Protect message endpoint (default: true)
}
}
}
}
});
클라이언트는 Authorization 헤더에 유효한 JWT 토큰을 포함해야 합니다.
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
API 키 인증
import { MCPServer, APIKeyAuthProvider } from "mcp-framework";
const server = new MCPServer({
transport: {
type: "sse",
options: {
auth: {
provider: new APIKeyAuthProvider({
keys: [process.env.API_KEY],
headerName: "X-API-Key" // Optional (default: "X-API-Key")
})
}
}
}
});
클라이언트는 X-API-Key 헤더에 유효한 API 키를 포함해야 합니다.
사용자 정의 인증
AuthProvider 인터페이스를 구현하여 고유한 인증 공급자를 구현할 수 있습니다.
import { AuthProvider, AuthResult } from "mcp-framework";
import { IncomingMessage } from "node:http";
class CustomAuthProvider implements AuthProvider {
async authenticate(req: IncomingMessage): Promise<boolean | AuthResult> {
// Implement your custom authentication logic
return true;
}
getAuthError() {
return {
status: 401,
message: "Authentication failed"
};
}
}
특허
MIT