Skip to main content
Glama
enesjakozh
stevennevins

MCP Server Template

by stevennevins
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

MCP 서버 템플릿

TypeScript에서 모델 컨텍스트 프로토콜(MCP) 서버를 생성하기 위한 템플릿입니다. 이 템플릿은 적절한 도구, 타입 안전성 및 모범 사례를 통해 MCP 호환 서버를 구축하기 위한 탄탄한 기반을 제공합니다.

특징

  • 🚀 전체 TypeScript 지원

  • 🏗️ 컨테이너 기반 종속성 주입

  • 📦 DataProcessor 인터페이스를 갖춘 서비스 기반 아키텍처

  • 🛠️ 테스트를 통한 도구 구현 예시

  • 🧪 Vitest 테스트 프레임워크

  • 📝 유형 정의

  • 🔌 MCP SDK 통합

Related MCP server: MCP Server Template

시작하기

개발

  1. 종속성 설치:

    지엑스피1

  2. 핫 리로드로 개발 서버를 시작합니다.

    npm run dev

  3. 프로젝트를 빌드하세요:

    npm run build

  4. 테스트 실행:

    npm test

  5. 프로덕션 서버를 시작합니다.

    npm start

프로젝트 구조

src/
├── index.ts          # Entry point
├── interfaces/       # Interface definitions
│   └── tool.ts      # DataProcessor interface
└── tools/           # Tool implementations
    └── example.ts   # Example tool

도구 만들기

  1. src/tools/example.ts 의 예제에 따라 도구와 핸들러를 내보내세요.

    // In your-tool.ts
export const YOUR_TOOLS = [
  {
    name: "your-tool-name",
    description: "Your tool description",
    parameters: {
      // Your tool parameters schema
    },
  },
];

export const YOUR_HANDLERS = {
  "your-tool-name": async (request) => {
    // Your tool handler implementation
    return {
      toolResult: {
        content: [{ type: "text", text: "Result" }],
      },
    };
  },
};

  2. src/index.ts 의 ALL_TOOLS 및 ALL_HANDLERS 상수에 도구를 등록합니다.

    // In src/index.ts
import { YOUR_TOOLS, YOUR_HANDLERS } from "./tools/your-tool.js";

// Combine all tools
const ALL_TOOLS = [...EXAMPLE_TOOLS, ...YOUR_TOOLS];
const ALL_HANDLERS = { ...EXAMPLE_HANDLERS, ...YOUR_HANDLERS };

서버는 자동으로 다음을 수행합니다.

  • 사용 가능한 도구에 도구를 나열하세요

  • 입력 검증 처리

  • 도구에 대한 프로세스 요청

  • MCP 프로토콜에 따라 응답 형식 지정

테스트

템플릿에는 로컬 테스트를 위한 내장 TestClient와 시각적 디버깅을 위한 MCP Inspector가 포함되어 있습니다.

TestClient 사용

TestClient는 도구를 테스트하는 간단한 방법을 제공합니다.

import { TestClient } from "./utils/TestClient";

describe("YourTool", () => {
  const client = new TestClient();

  it("should process data correctly", async () => {
    await client.assertToolCall(
      "your-tool-name",
      { input: "test" },
      (result) => {
        expect(result.toolResult.content).toBeDefined();
      }
    );
  });
});

MCP Inspector 사용

템플릿에는 도구의 시각적 디버깅을 위한 MCP 검사기가 포함되어 있습니다.

  1. 검사기를 시작합니다.

    npx @modelcontextprotocol/inspector node dist/index.js

  2. http://localhost:5173 에서 검사기 UI를 엽니다.

검사관은 다음을 제공합니다.

  • 테스트 도구를 위한 시각적 인터페이스

  • 실시간 요청/응답 모니터링

  • 도구 메타데이터 검사

  • 대화형 테스트 환경

커서를 사용한 로컬 테스트

Cursor를 사용하여 로컬로 MCP 서버를 테스트하려면:

  1. 패키지를 빌드하고 연결하세요.

    npm run build
npm run link

  2. 바이너리가 작동하는지 확인하세요.

    npx example-mcp-tool

  3. 커서에 서버를 추가합니다.

    • 커서 설정 열기

    • 기능 탭으로 이동

    • MCP 서버 섹션으로 스크롤하세요

    • "서버 추가"를 클릭하세요

    • "명령" 유형을 선택하세요

    • 이름을 지정합니다(예: "로컬 예제 도구")

    • 명령을 입력하세요: npx example-mcp-tool

    • 확인을 클릭하세요

  4. MCP 서버 섹션에 서버가 실행 중으로 표시되는지 확인하여 Cursor에서 서버가 올바르게 시작되는지 확인하세요.

참고: 코드를 변경한 경우 다시 빌드하고 다시 링크하는 것을 잊지 마세요.

npm run build
npm run link

테스트가 끝나면 패키지의 연결을 해제할 수 있습니다.

npm run unlink

이렇게 하면 개발 중에 생성된 글로벌 심볼릭 링크가 제거됩니다.

Available Tools

1 tool
example-toolC

An example tool that processes input data

ParametersJSON Schema
NameRequiredDescriptionDefault
inputYesInput string to process

TDQS

C2.6/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the tool 'processes input data', which implies some action but doesn't reveal behavioral traits like whether it's read-only, destructive, requires authentication, has side effects, or rate limits. This leaves significant gaps in understanding how the tool behaves.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence with no wasted words, making it appropriately concise. However, it's front-loaded with the basic purpose but lacks structure or additional details that could enhance clarity, keeping it simple but under-specified.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (1 parameter, no output schema, no annotations), the description is incomplete. It doesn't explain what 'processes' means, the expected output, or behavioral context, leaving the agent with insufficient information to use the tool effectively despite the straightforward schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description adds no specific meaning about the 'input' parameter beyond what the schema provides, which has 100% coverage and describes it as 'Input string to process'. With high schema coverage, the baseline is 3, as the schema adequately documents the parameter, and the description doesn't compensate or add further semantics.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states the tool 'processes input data', which provides a basic purpose but is vague about what 'processes' entails. It doesn't specify the type of processing or outcome, and with no sibling tools, differentiation isn't needed. This is a minimal viable description that communicates a general function without specifics.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description offers no guidance on when to use this tool, such as context, prerequisites, or alternatives. With no sibling tools, it doesn't need to distinguish from others, but it lacks any usage instructions or scenarios, leaving the agent without direction on appropriate application.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 1 tool update
    • First observedexample-tool
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

C2.8/5.0

Scored across 1 tool

Disambiguation5/5

With only one tool, there is no possibility of confusion or overlap between tools, as there are no other tools to compare it against. The single tool's purpose is clearly defined, eliminating any ambiguity in tool selection.

Naming Consistency5/5

Since there is only one tool, naming consistency is inherently perfect—there are no other tools to create inconsistency. The tool name 'example-tool' follows a simple, clear pattern without any conflicting conventions to evaluate.

Tool Count2/5

A single tool is generally too few for a server's purpose, as it limits functionality and suggests an incomplete or trivial implementation. For a server named 'MCP Server Template', one tool feels insufficient to demonstrate a coherent set of capabilities, making it borderline inadequate.

Completeness1/5

The server's purpose is unclear from the name 'MCP Server Template', but with only one generic tool ('example-tool'), there are significant gaps in coverage. It lacks any CRUD operations, lifecycle management, or domain-specific functions, making it severely incomplete for any practical application.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

Appeared in Searches