Skip to main content
Glama
deenesjakoruzh
Freddymhs

template-mcp

by Freddymhs
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Hybrid

template-mcp

MCP (Model Context Protocol) 服务器模板，支持 TypeScript、Zod 验证和双重传输（stdio/HTTP）。兼容任何 MCP 客户端：Claude Code、Claude Desktop、Cursor、VS Code Copilot、Windsurf、Cline 等。

特性

  • 双重传输：stdio（本地）和 Streamable HTTP（远程）

  • TypeScript 严格模式，使用 ESM 模块

  • Zod 验证：用于工具输入模式

  • Joi 环境变量验证（启动时快速失败）

  • Pino 日志记录：输出到 stderr（stdio 安全）

  • 模块化架构：工具、资源和提示词作为独立模块

  • 工厂模式：createServer() 以支持可测试性

  • 完整测试套件：使用 MCP SDK 内存传输

  • 高质量工具链：ESLint + Prettier + Husky + lint-staged

  • Docker 就绪：多阶段构建

  • CI/CD：GitHub Actions 流水线

Related MCP server: xmcp Application

快速开始

pnpm install
pnpm dev

脚本

脚本

描述

pnpm dev

启动并热重载 (tsx watch)

pnpm build

编译 TypeScript + 解析别名

pnpm start

运行编译后的服务器

pnpm test

运行测试

pnpm lint

代码检查

pnpm type-check

类型检查（不生成文件）

配置

将 .env.example 复制为 .env 并进行调整：

变量

默认值

描述

MCP_TRANSPORT

stdio

传输方式：stdio 或 http

PORT

3000

HTTP 端口（仅用于 http 传输）

LOG_LEVEL

info

Pino 日志级别

NODE_ENV

development

环境

项目结构

src/
├── main.ts              # Entrypoint: transport selection
├── server.ts            # createServer() factory
├── config/              # Env validation + constants
├── common/              # Logger, error helpers, types
├── tools/               # MCP tools (callable by LLMs)
├── resources/           # MCP resources (read-only data)
└── prompts/             # MCP prompts (reusable templates)

添加新工具

  1. 创建 src/tools/my-tool.tool.ts：

import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { z } from 'zod';

export function registerMyTool(server: McpServer): void {
  server.registerTool(
    'my_tool',
    {
      title: 'My Tool',
      description: 'What this tool does',
      inputSchema: {
        param: z.string().describe('Parameter description'),
      },
      annotations: {
        readOnlyHint: true,
        destructiveHint: false,
        idempotentHint: true,
        openWorldHint: false,
      },
    },
    async ({ param }) => ({
      content: [{ type: 'text', text: `Result: ${param}` }],
    }),
  );
}

  1. 在 src/tools/index.ts 中注册：

import { registerMyTool } from './my-tool.tool.js';

export function registerTools(server: McpServer): void {
  registerGreetTool(server);
  registerMyTool(server); // add here
}

  1. 在 src/tools/__tests__/my-tool.tool.spec.ts 中添加测试

客户端配置

Claude Code

添加到 .claude/settings.json：

{
  "mcpServers": {
    "template-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/template-mcp/dist/main.js"]
    }
  }
}

Claude Desktop

添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "template-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/template-mcp/dist/main.js"]
    }
  }
}

Cursor

添加到 Cursor 设置 > MCP Servers：

{
  "mcpServers": {
    "template-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/template-mcp/dist/main.js"]
    }
  }
}

VS Code (Copilot)

添加到 .vscode/settings.json：

{
  "mcp": {
    "servers": {
      "template-mcp": {
        "command": "node",
        "args": ["/absolute/path/to/template-mcp/dist/main.js"]
      }
    }
  }
}

Docker

# Build
docker build -t template-mcp .

# Run (HTTP mode, used for remote access)
docker run -p 3000:3000 template-mcp

技术栈

  • Node.js 22 + TypeScript (严格模式, ESM)

  • MCP SDK v1 (@modelcontextprotocol/sdk)

  • Zod (工具输入验证)

  • Joi (环境变量验证)

  • Pino (stderr 日志)

  • Vitest (测试)

  • ESLint + Prettier + Husky

验证

以下所有内容均已验证并 100% 可用。

代码质量

检查

命令

Lint + 格式化

pnpm lint

严格类型检查

pnpm type-check

构建 (tsc + alias)

pnpm build

单元测试 (11/11)

pnpm test

套件

覆盖范围

greet.tool.spec.ts (5)

列表、休闲/正式/热情风格、拒绝空名称

server-info.resource.spec.ts (2)

列表、JSON 字段 (name, version, uptime, timestamp)

summarize.prompt.spec.ts (4)

列表、简要/要点风格、数字强制转换、默认值

无需网络或端口 — 使用 SDK 的 InMemoryTransport。

运行时 — stdio 传输（默认模式）

echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}' \
  | MCP_TRANSPORT=stdio node dist/main.js

JSON-RPC 响应在 stdout，日志在 stderr。

运行时 — HTTP 传输

MCP_TRANSPORT=http PORT=3100 node dist/main.js &
# Initialize → capturar Mcp-Session-Id del header
# tools/list, resources/list, prompts/list, tools/call greet, resources/read info://server

已验证端点

预期结果

tools/call greet {"name":"Freddy","style":"casual"}

"Hey Freddy! How's it going?"

resources/read info://server

包含 name, version, uptime, nodeVersion, timestamp 的 JSON

Docker

docker build -t template-mcp .  # multi-stage: base → deps → build → production
docker run -p 3000:3000 template-mcp  # arranca en HTTP mode

CI (GitHub Actions)

pnpm install → pnpm lint → pnpm build → pnpm test 在每次推送到 main/master 分支或提交 PR 时运行。

提交流水线 (本地)

git commit → husky → lint-staged → eslint --fix + prettier --write (仅限暂存文件)

已知差距

  • HTTP 传输无自动化测试 (中)：单元测试使用 InMemoryTransport；HTTP 传输 (StreamableHTTPServerTransport) 仅通过 curl 手动验证。对于远程生产环境，需添加真实会话的集成测试

  • MCP 客户端集成 (中)：通过添加到 .claude/settings.json 或 Cursor 手动验证，并确认工具/资源/提示词出现在客户端中

  • 极端工具输入 (低)：超长字符串、格式错误的 unicode — Zod 会拒绝它们，但错误响应未通过 HTTP 进行测试

  • 并发会话 (低)：超出模板范围

Available Tools

1 tool
greetGreet UserA
Read-onlyIdempotent

Generates a personalized greeting message. Use this tool when you need to greet someone by name with an optional custom greeting style.

ParametersJSON Schema
NameRequiredDescriptionDefault
nameYesThe name of the person to greet
styleNoThe greeting style to usecasual

TDQS

A4.2/5.0
Behavior4/5

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

Annotations already indicate readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so the description does not need to repeat those. It adds the behavioral detail that the greeting is 'personalized' and that style is optional with a default value, which is sufficient given the high annotation coverage.

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

Conciseness5/5

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

The description is a single, clear sentence that is front-loaded with the main action and immediately provides usage guidance. Every word is necessary and there is no redundant information.

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

Completeness4/5

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

Given the tool's simplicity (2 parameters, no output schema, no nested objects) and the rich annotations, the description is complete enough. It covers the purpose and usage adequately. No output schema is needed as the return is self-evident.

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?

Schema description coverage is 100%, so the schema already documents both parameters thoroughly (name with length constraints, style with enum and default). The description adds no new parameter information beyond what's in the schema, earning a baseline score of 3.

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

Purpose5/5

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

The description clearly states that the tool generates a personalized greeting message, with a specific verb ('greet') and resource ('someone by name'). It also mentions the optional custom greeting style, distinguishing it from any potential siblings (though none exist).

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

Usage Guidelines4/5

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

The description explicitly says 'Use this tool when you need to greet someone by name with an optional custom greeting style,' providing clear usage context. However, it does not specify when not to use it or mention any alternatives, but since there are no siblings, this is adequate.

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 updatev1.0.0
    • First observedgreet
Deploy Server
Shareable, User-Owned Context BackendPeople, applications, and agents read, write, and coordinate together in one context lake. Reach it over MCP, a CLI, a Python SDK, or REST.fulcradynamics.comAd

TDQS

A3.8/5.0

Scored across 1 tool

Disambiguation5/5

Only one tool exists, so there is no ambiguity in choosing between tools.

Naming Consistency3/5

With only one tool, consistency is not applicable, but the name 'greet' is clear and follows a common verb pattern.

Tool Count2/5

A single tool for a server called 'template-mcp' suggests an extremely narrow scope, which is likely insufficient for meaningful tasks.

Completeness2/5

The server only offers a greeting function, which is too limited for any substantial workflow; missing any broader functionality.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • MCP Base Server

    yone-k
    A
    license
    Not graded
    quality
    D
    maintenance
    A TypeScript-based template for rapidly developing MCP servers with modular tool architecture, built-in validation using Zod schemas, and comprehensive error handling.
    9 npm
    MIT

  • xmcp Application

    SumitNawathe
    F
    license
    Not graded
    quality
    D
    maintenance
    A Model Context Protocol (MCP) server template designed for building structured tools, prompts, and resources with built-in support for HTTP and STDIO transports. It provides a standardized framework for developers to create and deploy AI-driven services using TypeScript and Zod schema validation.
    8 npm
    -

  • MCP Starter Kit

    iamdipanshusingh
    A
    license
    Not graded
    quality
    D
    maintenance
    A minimal TypeScript MCP server template with example tool, Zod validation, stdio transport, and dotenv setup.
    8 npm
    MIT