项目简介

这是一个基于TypeScript实现的Model Context Protocol (MCP) 服务器基础框架。它为开发者提供了一个快速构建和部署MCP服务器的起点，集成了日志、错误处理、ID生成、速率限制等生产级工具，并提供了Echo工具和Echo资源作为示例。

主要功能点

遵循MCP协议标准: 实现了MCP的JSON-RPC通信协议，能够处理来自LLM客户端的资源访问和工具调用请求。
包含MCP服务器实现: 提供了完整的服务器端代码结构，而非仅仅客户端库。
示例工具和资源: 内置了Echo工具和Echo资源，演示了如何注册和处理工具调用及资源访问。
多种传输协议支持: 支持通过标准输入/输出 (Stdio) 或 HTTP (包含 Server-Sent Events) 进行通信。
生产级开发工具: 集成了完善的日志记录、错误处理、输入校验与净化、请求上下文管理等实用功能。
模块化设计: 代码结构清晰，易于理解和扩展，方便添加自定义的工具、资源和Prompt。

安装步骤

要设置并运行此项目，请按照以下步骤操作：

克隆仓库:

git clone https://github.com/cyanheads/mcp-ts-template.git
cd mcp-ts-template

安装依赖: 使用 npm 安装项目所需的所有依赖项：
```
npm install
```
构建项目: 编译TypeScript代码：
```
npm run build
```
这将在 'dist' 目录下生成可执行的JavaScript文件。

服务器配置 (供MCP客户端参考)

此MCP服务器可以通过环境变量配置其运行方式。要连接到此服务器，您的MCP客户端（或其他兼容的LLM客户端）需要知道如何启动或连接到它。以下是客户端配置此服务器时可能需要的关键信息，以及如何通过环境变量影响服务器行为：

服务器名称: 默认是 'mcp-ts-template'。
传输协议 (Transport Type):
- 'stdio' (默认): 通过标准输入/输出与客户端通信。
- 'http': 通过HTTP协议通信，客户端连接到指定的URL。
- 服务器通过环境变量 'MCP_TRANSPORT_TYPE' 设置此项（例如 'export MCP_TRANSPORT_TYPE=http'）。
启动命令 (Command) 及参数 (Args):
- 如果服务器使用 'stdio' 模式，客户端通常需要指定执行此服务器进程的命令和参数。
  - 'command': 通常是 'node'
  - 'args': 通常是 MCP服务器编译后的入口文件路径，例如 './dist/index.js'。
- 如果服务器使用 'http' 模式，客户端的 'command' 字段应是服务器监听的基准URL。
  - 'command': 例如 'http://127.0.0.1:3000/mcp' (端口3000是默认值，路径 '/mcp' 是固定的)。
  - 'args': 通常为空。
- 服务器的HTTP端口可以通过环境变量 'MCP_HTTP_PORT' 配置 (默认 3000)。
- 服务器的HTTP监听地址可以通过环境变量 'MCP_HTTP_HOST' 配置 (默认 '127.0.0.1')。
环境变量 (Env): 客户端配置中可以为启动的服务器进程设置额外的环境变量 (主要用于 'stdio' 模式)，例如 'LOG_LEVEL'。服务器会读取这些以及系统已有的环境变量。

例如，在MCP客户端的配置文件（如 'mcp-config.json'）中，配置此服务器的示例条目可能像这样：

连接到 Stdio 模式的服务器: 描述：客户端需要指定启动服务器进程的Node.js命令和入口文件路径。

{
  "my-ts-server-stdio": {
    "command": "node",
    "args": ["/path/to/your/cloned/repo/dist/index.js"],
    "env": {
      "LOG_LEVEL": "debug"
    },
    "transportType": "stdio"
  }
}

连接到 HTTP 模式的服务器: 描述：客户端需要指定服务器监听的URL。

{
  "my-ts-server-http": {
    "command": "http://127.0.0.1:3000/mcp",
    "args": [],
    "transportType": "http"
  }
}

请根据您的实际部署路径、端口和配置选择合适的模式。

基本使用方法

构建完成后，您可以运行内置的示例MCP服务器：

以 Stdio 模式运行 (默认):

npm start
# 或明确指定：
npm run start:stdio

服务器将监听标准输入进行通信。

以 HTTP 模式运行:
```
npm run start:http
```
服务器将启动一个HTTP监听器 (默认在 'http://127.0.0.1:3000/mcp')，客户端可以通过HTTP连接。

一旦服务器启动，兼容的MCP客户端（如同一仓库中的客户端模块，或独立的MCP客户端应用）就可以通过上述配置信息连接到它，并利用其提供的Echo工具和Echo资源。

要使用此模板开发您自己的MCP服务器，请参考仓库中的 'src/mcp-server' 目录结构和开发指南，特别是关于添加新的工具和资源的部分。

关键词

项目简介

主要功能点

安装步骤

服务器配置 (供MCP客户端参考)

基本使用方法

信息