작업 API 서버 - MCP TypeScript 구현

TypeScript로 작성된 작업 관리 API를 위한 모델 컨텍스트 프로토콜(MCP) 구현입니다. 이 프로젝트는 참조 구현체이자 기능적 작업 관리 서버 역할을 합니다.

개요

이 MCP 서버는 외부 작업 API 서비스에 연결하여 작업 관리를 위한 표준화된 인터페이스를 제공합니다. 두 가지 런타임 모드를 지원합니다.

STDIO 모드 : CLI 기반 애플리케이션 및 AI 에이전트를 위한 표준 입출력 통신
HTTP+SSE 모드 : 브라우저 및 HTTP 기반 클라이언트를 위한 서버 전송 이벤트가 있는 웹 접근 가능 서버

이 서버는 완전한 작업 관리 작업, 광범위한 검증, 견고한 오류 처리 기능을 제공합니다.

특징

작업 관리 운영 :
- 필터링 기능을 사용하여 기존 작업 나열
- 사용자 정의 가능한 속성으로 새 작업 만들기
- 작업 세부 정보(설명, 상태, 범주, 우선순위) 업데이트
- 완료되었거나 더 이상 필요하지 않은 작업을 삭제합니다.
듀얼 인터페이스 모드 :
- 명령줄 및 AI 에이전트 통합을 위한 STDIO 프로토콜 지원
- 브라우저 기반 액세스를 위한 웹 인터페이스가 있는 HTTP+SSE 프로토콜
MCP 프로토콜 구현 :
- 모델 컨텍스트 프로토콜의 완전한 구현
- 작업 데이터 구조에 대한 리소스
- 작업 운영을 위한 도구
- 오류 처리 및 정보 메시지
품질 보증 :
- 검증을 위한 종합 테스트 클라이언트
- 테스트 완료 후 자동 서버 종료
- API 응답의 자세한 검증

시작하기

필수 조건

Node.js 16.x 이상
npm 또는 pnpm 패키지 관리자

설치

저장소를 복제합니다.지엑스피1
종속성 설치:
npm install
또는 pnpm을 사용하세요:
pnpm install
Task API 자격 증명으로 .env 파일을 만듭니다.
TASK_MANAGER_API_BASE_URL=https://your-task-api-url.com/api TASK_MANAGER_API_KEY=your_api_key_here TASK_MANAGER_HTTP_PORT=3000
프로젝트를 빌드하세요:
npm run build

서버 실행

STDIO 모드(CLI/AI 통합용)

npm start

또는

node dist/index.js

HTTP 모드(웹 접속용)

npm run start:http

또는

node dist/http-server.js

기본적으로 HTTP 서버는 포트 3000에서 실행됩니다. TASK_MANAGER_HTTP_PORT 환경 변수를 설정하여 이를 변경할 수 있습니다.

테스트

기능을 검증하기 위해 포괄적인 테스트 모음을 실행합니다.

npm test

이렇게 하면:

프로젝트를 빌드하세요
서버 인스턴스 시작
테스트 클라이언트를 서버에 연결합니다
모든 작업 작업을 실행합니다.
정답 확인
서버를 자동으로 종료합니다

MCP 클라이언트 사용

STDIO 클라이언트

애플리케이션에서 STDIO 서버에 연결하려면:

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
import * as path from 'path';

// Create transport
const transport = new StdioClientTransport({
  command: 'node',
  args: [path.resolve('path/to/dist/index.js')]
});

// Initialize client
const client = new Client(
  {
    name: "your-client-name",
    version: "1.0.0"
  },
  {
    capabilities: {
      prompts: {},
      resources: {},
      tools: {}
    }
  }
);

// Connect to server
await client.connect(transport);

// Example: List all tasks
const listTasksResult = await client.callTool({
  name: "listTasks",
  arguments: {}
});

// Example: Create a new task
const createTaskResult = await client.callTool({
  name: "createTask",
  arguments: {
    task: "Complete project documentation",
    category: "Documentation",
    priority: "high"
  }
});

// Clean up when done
await client.close();

HTTP 클라이언트

브라우저에서 HTTP 서버에 연결하려면:

<!DOCTYPE html>
<html>
<head>
  <title>Task Manager</title>
  <script type="module">
    import { Client } from 'https://cdn.jsdelivr.net/npm/@modelcontextprotocol/sdk/dist/esm/client/index.js';
    import { SSEClientTransport } from 'https://cdn.jsdelivr.net/npm/@modelcontextprotocol/sdk/dist/esm/client/sse.js';

    document.addEventListener('DOMContentLoaded', async () => {
      // Create transport
      const transport = new SSEClientTransport('http://localhost:3000/mcp');
      
      // Initialize client
      const client = new Client(
        {
          name: "browser-client",
          version: "1.0.0"
        },
        {
          capabilities: {
            prompts: {},
            resources: {},
            tools: {}
          }
        }
      );

      // Connect to server
      await client.connect(transport);
      
      // Now you can use client.callTool() for tasks
    });
  </script>
</head>
<body>
  <h1>Task Manager</h1>
  <!-- Your interface elements here -->
</body>
</html>

사용 가능한 도구

목록 작업

사용 가능한 모든 작업을 나열합니다.

const result = await client.callTool({
  name: "listTasks",
  arguments: {
    // Optional filters
    status: "pending", // Filter by status
    category: "Work",  // Filter by category
    priority: "high"   // Filter by priority
  }
});

createTask

새로운 작업을 생성합니다.

const result = await client.callTool({
  name: "createTask",
  arguments: {
    task: "Complete the project report",  // Required: task description
    category: "Work",                     // Optional: task category
    priority: "high"                      // Optional: low, medium, high
  }
});

업데이트 작업

기존 작업을 업데이트합니다.

const result = await client.callTool({
  name: "updateTask",
  arguments: {
    taskId: 123,                       // Required: ID of task to update
    task: "Updated task description",  // Optional: new description
    status: "done",                    // Optional: pending, started, done
    category: "Personal",              // Optional: new category
    priority: "medium"                 // Optional: low, medium, high
  }
});

작업 삭제

작업을 삭제합니다.

const result = await client.callTool({
  name: "deleteTask",
  arguments: {
    taskId: 123  // Required: ID of task to delete
  }
});

환경 변수

변하기 쉬운	설명	기본
작업 관리자 API 기반 URL	외부 작업 API에 대한 URL	없음 (필수)
작업 관리자 API 키	인증을 위한 API 키	없음 (필수)
작업 관리자 HTTP 포트	HTTP 서버용 포트	3000
포트	대체 포트 이름(우선순위 있음)	없음

프로젝트 구조

mcp-template-ts/
├── dist/               # Compiled JavaScript files
├── src/                # TypeScript source files
│   ├── index.ts        # STDIO server entry point
│   ├── http-server.ts  # HTTP+SSE server entry point
│   ├── test-client.ts  # Test client implementation
├── .env                # Environment variables
├── package.json        # Project dependencies
├── tsconfig.json       # TypeScript configuration
└── README.md           # Project documentation

개발

감시 모드에서 TypeScript 컴파일러를 시작합니다.
npm run watch
변경 사항을 확인하기 위해 테스트를 실행합니다.
npm test

특허

이 프로젝트는 MIT 라이선스에 따라 라이선스가 부여되었습니다. 자세한 내용은 라이선스 파일을 참조하세요.

감사의 말

이 프로젝트는 MCP 프로토콜 구현을 위해 @modelcontextprotocol/sdk를 사용합니다.
AI 툴링 및 웹 애플리케이션과의 통합을 위해 제작됨

Task API Server

Integrations