Xava Labs MCP 템플릿

Xava Labs Typescript MCP 템플릿

xava-labs/typescript-agent-framework에 대한 MCP(모델 컨텍스트 프로토콜) 부트스트래핑을 위한 템플릿 저장소입니다.

시작하기

저장소 설정

옵션 A: 이 템플릿을 사용하세요

이 저장소 상단의 "이 템플릿 사용" 버튼을 클릭하세요.
새 저장소를 복제하세요

옵션 B: Cloudflare에 배포 버튼 사용

다음 버튼을 사용하면 조직에 새 저장소가 생성되고 Cloudflare를 사용하여 CI/CD가 설정됩니다.

참고: Deploy 명령이 작동하려면 구성에 npm run deploy 만 필요합니다.

옵션 C: Cloudflare create 사용

Wrangler를 사용하여 이 템플릿을 기반으로 새 프로젝트를 만들 수 있습니다.

편의를 위해 다음 텍스트를 복사하세요

xava-labs/mcp-template

다음 명령을 실행하고 대화형 프롬프트에 따라 이름을 선택한 다음 "GitHub 저장소의 템플릿"으로 시작한 다음 사용하려는 템플릿에 대한 위의 텍스트를 붙여넣습니다.

지엑스피1

위의 방법 중 하나를 완료한 후 터미널에서 다음 명령을 실행하여 시작하세요.

npm install
npm run dev

위의 내용은 다음 URL을 사용하여 서버리스 Cloudflare 호환 MCP 서버를 부트스트랩합니다.

/ws - 웹소켓 연결 엔드포인트
/sse - SSE 연결 엔드포인트

특징

WebSocket 클라이언트 지원 : 실시간 양방향 통신을 위한 공식 WebSocket 클라이언트 포함
SSE 클라이언트 지원 : 서버-클라이언트 스트리밍을 위한 서버-전송 이벤트 클라이언트 포함
MCP Inspector : 개발 중 MCP 디버깅 및 모니터링
Cloudflare Workers 통합 : 엣지 컴퓨팅 기능을 위해 Cloudflare Workers 기반으로 구축됨
통합 테스트 모음 : 로컬 미니플레어 서비스(D1/KV/기타)와의 전체 통합 테스트를 수행하는 Websocket 및 SSE 테스트 도구로 모킹 없이 기능을 쉽게 테스트할 수 있습니다.

사용 가능한 스크립트

npm run dev : MCP Inspector(포트 6274)와 Cloudflare Worker(포트 8787)를 동시에 실행합니다.
npm start : Cloudflare Worker(포트 8787)만 실행합니다.
npm test : Vitest로 테스트를 실행합니다.
npm run deploy : MCP를 Cloudflare Workers에 배포합니다.
npm run cf-typegen : Cloudflare Workers에 대한 TypeScript 유형을 생성합니다(wrangler.jsonc에 새 변경 사항을 추가할 때마다 실행).

개발

이 템플릿은 상태 저장 연결을 위해 지속형 객체를 사용하는 MCP 서버를 구현합니다. 기본 프로젝트 구조는 기능 확장을 위한 두 가지 주요 접근 방식을 제공합니다.

McpHonoServerDO 구현

기본적으로 이 템플릿은 MCP 서버와 빠르고 가벼운 웹 프레임워크인 Hono를 결합한 McpHonoServerDO 사용합니다. 이는 깔끔한 라우팅 시스템과 미들웨어 기능을 제공합니다.

도구, 리소스 및 프롬프트를 사용하여 확장

주요 서버 구현은 src/server.ts 에 있으며 McpHonoServerDO 확장합니다.

export class ExampleMcpServer extends McpHonoServerDO {
  // Required abstract method implementation
  getImplementation(): Implementation {
    return {
      name: 'ExampleMcpServer',
      version: '1.0.0',
    };
  }

  // Configure server by adding tools, resources, and prompts
  configureServer(server: McpServer): void {
    setupServerTools(server);
    setupServerResources(server);
    setupServerPrompts(server);
  }
}

기능을 추가하려면 다음 모듈을 사용하세요.

도구 ( src/tools.ts ): 클라이언트가 호출할 수 있는 함수를 정의합니다.

export function setupServerTools(server: McpServer) {
  server.tool(
    'tool_name',           // Name of the tool
    'Tool description',    // Description
    {                      // Parameters schema using zod
      param1: z.string().describe('Parameter description'),
    },       
    async ({ param1 }) => {
      // Tool implementation
      return {
        content: [
          {
            type: "text",
            text: `Result: ${param1}`
          }
        ]
      };
    }
  );
}

리소스 ( src/resources.ts ): 클라이언트가 액세스할 수 있는 영구 리소스를 정의합니다.

export function setupServerResources(server: McpServer) {
  server.resource(
    'resource_name',
    'resource://path/{id}',
    async (uri: URL) => {
      // Resource implementation
      return {
        contents: [
          {
            text: `Resource data`,
            uri: uri.href
          }
        ]
      };
    }
  );
}

프롬프트 ( src/prompts.ts ): 프롬프트 템플릿 정의

export function setupServerPrompts(server: McpServer) {
  server.prompt(
    'prompt_name',
    'Prompt description',
    () => ({
      messages: [{
        role: 'assistant',
        content: {
          type: 'text',
          text: `Your prompt text here`
        }
      }]
    })
  );
}

Hono를 사용하여 경로 사용자 지정

McpHonoServerDO 사용하여 사용자 정의 HTTP 엔드포인트를 추가하려면 setupRoutes 메서드를 확장합니다.

export class ExampleMcpServer extends McpHonoServerDO {
  // Other methods...

  protected setupRoutes(app: Hono<{ Bindings: Env }>): void {
    // Call the parent implementation to set up MCP routes
    super.setupRoutes(app);
    
    // Add your custom routes
    app.get('/api/status', (c) => {
      return c.json({ status: 'ok' });
    });
    
    app.post('/api/data', async (c) => {
      const body = await c.req.json();
      // Process data
      return c.json({ success: true });
    });
  }
}

McpServerDO 구현(네이티브 Cloudflare 라우팅)

HTTP 요청 처리를 더 세밀하게 제어해야 하는 경우 McpServerDO 직접 확장할 수 있습니다. 이렇게 하면 fetch 메서드를 완벽하게 제어할 수 있습니다.

export class CustomMcpServer extends McpServerDO {
  // Required abstract method implementations
  getImplementation(): Implementation {
    return {
      name: 'CustomMcpServer',
      version: '1.0.0',
    };
  }
  
  configureServer(server: McpServer): void {
    setupServerTools(server);
    setupServerResources(server);
    setupServerPrompts(server);
  }
  
  // Override the fetch method for complete control over routing
  async fetch(request: Request): Promise<Response> {
    const url = new URL(request.url);
    const path = url.pathname;
    
    // Handle custom routes
    if (path === '/api/custom') {
      return new Response(JSON.stringify({ custom: true }), {
        headers: { 'Content-Type': 'application/json' }
      });
    }
    
    // Pass through MCP-related requests to the parent implementation
    return super.fetch(request);
  }
}

이 방법은 다음과 같은 경우에 유용합니다.

사용자 정의 논리를 사용하여 특정 경로를 처리합니다.
복잡한 미들웨어 또는 인증 구현
MCP 핸들러에 도달하기 전에 요청을 가로채거나 수정합니다.
표준 MCP 구현을 넘어 사용자 정의 WebSocket 또는 SSE 엔드포인트 추가

예시

CRUD Todo 목록 예시

완전한 작동 예제를 보려면 다음을 보여주는 CRUD Todo List MCP 예제를 확인하세요.

MCP 도구를 사용한 전체 CRUD 작업
지속성을 위한 SQLite 데이터베이스 통합
WebSocket/SSE를 통한 실시간 업데이트
포괄적인 오류 처리
고급 필터링 및 정렬 기능
풍부한 프롬프트와 리소스

지역 사회

도움을 받고, 아이디어를 공유하고, 프로젝트에 기여하려면 커뮤니티에 가입하세요.

Discord : 기능 요청, 지원 및 토론을 위해 #mcp 채널에 가입하세요

기여하다

이 템플릿을 개선하기 위한 여러분의 참여를 기다립니다! 참여 방법은 다음과 같습니다.

저장소 포크 : 변경 사항을 적용하기 위해 포크를 생성합니다.
브랜치 만들기 : 새 브랜치에서 변경 사항을 만듭니다.
git checkout -b feature/your-feature-name
변경 사항 커밋 : 의미 있는 커밋을 만드세요
git commit -m "Add feature: brief description"
포크에 푸시 : 변경 사항을 포크에 푸시합니다.
git push origin feature/your-feature-name
풀 리퀘스트 생성 : 변경 사항에 대한 자세한 설명과 함께 PR을 엽니다.

풀 리퀘스트 가이드라인

PR에 대해 명확하고 설명적인 제목을 제공하세요.
귀하의 PR이 무엇을 하는지에 대한 자세한 설명을 포함하세요
관련 문제를 참조하세요.
해당되는 경우 스크린샷이나 예를 포함하세요.
모든 테스트가 통과되었는지 확인하세요
PR을 단일 기능이나 수정 사항에 집중시키세요.

더 큰 변경 사항이나 기능에 대해서는 프로젝트 방향과의 일치 여부를 확인하기 위해 먼저 Discord 채널에서 논의하는 것이 좋습니다.

또는 위의 Cloudflare에 배포 버튼을 사용하여 GitHub에서 바로 배포할 수 있습니다.

특허

MIT

Xava Labs MCP Template

Integrations

Xava Labs Typescript MCP 템플릿

시작하기

저장소 설정

특징

사용 가능한 스크립트

개발

McpHonoServerDO 구현

도구, 리소스 및 프롬프트를 사용하여 확장

Hono를 사용하여 경로 사용자 지정

McpServerDO 구현(네이티브 Cloudflare 라우팅)

예시

CRUD Todo 목록 예시

관련 자료

핵심 패키지

선적 서류 비치

지역 사회

기여하다

풀 리퀘스트 가이드라인

특허

Related MCP Servers

Remote MCP Server

MCP SSE Server

Remote MCP Server on Cloudflare

Tiny SSE MCP Server