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();
특징
특허
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