Skip to main content
Glama
fist-maestro

MCP Servers

by fist-maestro
OverviewSchemaRelated ServersScoreDiscussions
TypeScript

MCP Servers 项目

基于 Model Context Protocol (MCP) 开发的服务集合，用于支持 Cursor IDE 的智能功能。目前包含示例服务和天气服务。

开发环境要求

  • Node.js >= 16.0.0

  • npm >= 8.0.0

  • TypeScript >= 4.5.0

  • Cursor IDE（最新版本）

Related MCP server: MCP Express Server

项目结构

mcp-servers/
├── src/                    # 源代码目录
│   ├── demo/              # 示例服务
│   │   ├── config/       # 配置层：常量、类型定义
│   │   │   ├── constants.ts    # 常量定义
│   │   │   └── types.ts        # 类型定义
│   │   ├── controllers/  # 控制器层：请求处理
│   │   │   └── GreetingController.ts  # 问候控制器
│   │   ├── service/      # 服务层：业务逻辑
│   │   │   └── GreetingService.ts     # 问候服务
│   │   ├── package.json  # 服务配置文件
│   │   ├── tsconfig.json # TypeScript 配置
│   │   └── index.ts      # 服务入口文件
│   │
│   └── weather/          # 天气服务
│       ├── config/       # 配置层：常量、类型定义
│       │   ├── constants.ts    # 常量定义
│       │   └── types.ts        # 类型定义
│       ├── controllers/  # 控制器层：请求处理
│       │   └── WeatherController.ts  # 天气控制器
│       ├── service/      # 服务层：业务逻辑
│       │   └── WeatherService.ts     # 天气服务
│       ├── package.json  # 服务配置文件
│       ├── tsconfig.json # TypeScript 配置
│       └── index.ts      # 服务入口文件
│
├── build/                  # 编译输出目录
├── node_modules/          # 依赖包
├── package.json           # 项目配置
├── tsconfig.json          # TypeScript 配置
└── README.md             # 项目文档

代码分层架构

项目采用三层架构设计，每个服务都遵循相同的结构模式：

1. 配置层（Config）

位置：服务目录/config/

  • 职责：

    • 定义常量和配置项

    • 声明类型和接口

    • 管理环境变量

  • 主要文件：

    • constants.ts: 常量定义

    • types.ts: 类型定义

  • 特点：

    • 集中管理配置

    • 类型安全

    • 易于维护和修改

2. 控制器层（Controllers）

位置：服务目录/controllers/

  • 职责：

    • 处理 MCP 请求和响应

    • 参数验证和错误处理

    • 调用服务层方法

  • 主要文件：

    • XXXController.ts: 具体业务控制器

  • 特点：

    • 请求参数验证

    • 错误处理和日志

    • 响应格式化

3. 服务层（Service）

位置：服务目录/service/

  • 职责：

    • 实现核心业务逻辑

    • 处理数据转换

    • 调用外部 API

  • 主要文件：

    • XXXService.ts: 具体业务服务

  • 特点：

    • 业务逻辑封装

    • 数据处理和转换

    • 外部服务集成

服务入口（index.ts）

位置：服务目录/index.ts

  • 职责：

    • 初始化服务实例

    • 注册 MCP 工具

    • 处理标准输入输出

  • 特点：

    • 统一的入口点

    • MCP 工具注册

    • 错误处理

开发流程

  1. 新建服务

    mkdir -p src/new-service/{config,controllers,service}

  2. 实现各层功能

    • 配置层：定义常量和类型

    • 控制器层：处理请求和响应

    • 服务层：实现业务逻辑

  3. 创建配置文件

    • package.json: 服务依赖和脚本

    • tsconfig.json: TypeScript 配置

  4. 编写入口文件

    • 创建 index.ts

    • 注册 MCP 工具

    • 实现请求处理

快速开始

1. 克隆项目

git clone <repository-url>
cd mcp-servers

2. 安装依赖

npm install

3. 构建项目

# 构建所有服务
npm run build

# 构建单个服务
npm run build:weather  # 构建天气服务
npm run build:demo    # 构建示例服务

4. 配置 MCP

编辑 ~/.cursor/mcp.json 文件：

{
  "mcpServers": {
    "weather": {
      "command": "node",
      "args": [
        "/your/path/to/mcp-servers/build/weather/index.js"
      ],
      "env": {
        "OPENWEATHER_API_KEY": "your_api_key_here"
      }
    }
  }
}

5. 启动服务

# 启动天气服务
npm run start:weather

# 启动示例服务
npm run start:demo

可用服务说明

1. 示例服务（Demo）

  • 位置：src/demo/

  • 功能：展示 MCP 服务的基本结构和开发方法

  • 特点：

    • 简单的请求响应示例

    • 基础错误处理

    • 代码注释完善，适合学习

2. 天气服务（Weather）

  • 位置：src/weather/

  • 功能：提供全球天气查询服务

  • 特点：

    • 实时天气查询

    • 5天天气预报

    • 支持多城市查询

    • 详细的天气信息

查看各服务详细文档：

开发指南

创建新服务

  1. 在 src 目录下创建新服务目录

  2. 参考现有服务的目录结构

  3. 实现必要的控制器和服务

  4. 在 package.json 添加相应的构建和启动脚本

调试方法

  1. 使用 console.error() 输出调试信息

  2. 检查 Cursor IDE 的 MCP 日志

  3. 使用 TypeScript 的源码映射功能

测试

# 运行所有测试
npm test

# 运行特定服务的测试
npm run test:weather

常见问题

  1. 服务无法启动

    • 检查端口占用

    • 确认环境变量配置

    • 验证构建输出

  2. API 调用失败

    • 检查 API Key 配置

    • 确认网络连接

    • 查看错误日志

  3. Cursor IDE 无法识别服务

    • 检查 MCP 配置

    • 重启 Cursor IDE

    • 确认服务状态

贡献指南

  1. Fork 项目

  2. 创建特性分支

  3. 提交变更

  4. 推送到分支

  5. 创建 Pull Request

许可证

MIT License

Available Tools

2 tools
get-current-weatherC

Get current weather for a location

ParametersJSON Schema
NameRequiredDescriptionDefault
cityYesCity name (e.g. Beijing, London)
countryNoCountry code (e.g. CN, GB)

TDQS

C2.9/5.0
Behavior2/5

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It states what the tool does but reveals nothing about behavioral traits: no information about rate limits, authentication requirements, error conditions, response format, or whether this is a read-only operation. The description is minimal and lacks essential operational context.

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 extremely concise at just 6 words: 'Get current weather for a location'. It's front-loaded with the core purpose and contains zero wasted words. This is an example of efficient communication where every word earns its place.

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 moderate complexity (2 parameters, no output schema, no annotations), the description is insufficiently complete. It states what the tool does but provides no context about when to use it, what it returns, or any behavioral characteristics. For a weather API tool that likely has rate limits and specific response formats, this leaves significant gaps for an AI agent.

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 parameter information beyond what's already in the schema. Since schema description coverage is 100% (both parameters have descriptions in the schema), the baseline score is 3. The description doesn't compensate with additional context about parameter usage, relationships, or examples beyond the schema's documentation.

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

Purpose4/5

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

The description clearly states the tool's purpose: 'Get current weather for a location'. It specifies the verb ('Get') and resource ('current weather'), making it understandable. However, it doesn't explicitly differentiate from its sibling tool 'get-forecast', which likely provides future weather predictions rather than current conditions.

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 provides no guidance on when to use this tool versus alternatives. There's no mention of the sibling tool 'get-forecast', nor any context about when current weather data is appropriate versus forecast data. The agent must infer usage from the tool name alone.

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

get-forecastC

Get 5-day weather forecast for a location

ParametersJSON Schema
NameRequiredDescriptionDefault
cityYesCity name (e.g. Beijing, London)
countryNoCountry code (e.g. CN, GB)

TDQS

C2.9/5.0
Behavior2/5

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It states the tool retrieves a forecast but omits critical details such as rate limits, authentication requirements, data freshness, or error handling. For a read operation without annotations, this leaves significant gaps in understanding how the tool behaves beyond its basic function.

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, efficient sentence that front-loads the core purpose without any wasted words. It's appropriately sized for a simple tool, making it easy to parse and understand quickly. Every part of the sentence contributes directly to clarifying the tool's function.

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 lack of annotations and output schema, the description is incomplete for effective use. It doesn't explain what the forecast data includes (e.g., temperature, precipitation), how results are structured, or any limitations. For a tool with two parameters and no structured output, more contextual detail is needed to guide the agent adequately.

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 input schema has 100% description coverage, with clear documentation for both parameters ('city' and 'country'). The description adds no additional semantic context beyond implying a 'location' parameter, which is already covered by the schema. This meets the baseline score of 3, as the schema does the heavy lifting without extra value from the description.

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

Purpose4/5

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

The description clearly states the action ('Get') and resource ('5-day weather forecast for a location'), making the purpose immediately understandable. It doesn't explicitly differentiate from the sibling 'get-current-weather' tool, which prevents a score of 5, but it's specific enough to convey what the tool does without being vague or tautological.

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 provides no guidance on when to use this tool versus the sibling 'get-current-weather' tool. It lacks any mention of alternatives, prerequisites, or contextual usage scenarios, leaving the agent to infer based on tool names alone. This minimal guidance is insufficient for optimal tool selection.

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

Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

B3.2/5.0
Disambiguation5/5

The two tools have clearly distinct purposes: one provides current weather data, while the other provides a 5-day forecast. There is no overlap or ambiguity between them, making it easy for an agent to select the correct tool based on the time horizon needed.

Naming Consistency5/5

Both tool names follow a consistent verb_noun pattern with hyphens (get-current-weather, get-forecast). The naming is predictable and readable, with no deviations in style or convention across the set.

Tool Count3/5

With only 2 tools, the server feels thin for a weather domain, as it lacks operations like historical data, alerts, or location search. While the tools cover basic current and forecast needs, the count is borderline low for typical agent workflows that might require more comprehensive weather data.

Completeness3/5

The server provides core current and forecast functions, but there are notable gaps for a weather service, such as no historical weather data, severe weather alerts, or location autocomplete. Agents can work around this for basic queries, but the surface is incomplete for more advanced use cases.

Maintenance

ActivityInactive
ResponsivenessSyncing

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • First MCP Server

    geka-evk
    A
    license
    Not graded
    quality
    D
    maintenance
    A TypeScript-based server project with comprehensive development tooling including testing, linting, and build configurations.
    MIT

  • MCP Express Server

    pr0methevs
    F
    license
    Not graded
    quality
    D
    maintenance
    A TypeScript-based MCP server template using Express.js and Server-Sent Events, providing example tools for echoing messages, performing calculations, and retrieving server time.

  • Starter MCP Server

    YunYouJun
    A
    license
    B
    quality
    D
    maintenance
    A template/boilerplate project for building Model Context Protocol (MCP) servers with TypeScript. Provides a starting point with configuration examples, development tools, and debugging setup.
    2
    1
    MIT

  • toni-mcp-server

    toni0402-han
    F
    license
    Not graded
    quality
    D
    maintenance
    A TypeScript MCP server boilerplate providing example tools and resources for rapid development and testing of Model Context Protocol servers.

Appeared in Searches

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/fist-maestro/mcp-servers'

If you have feedback or need assistance with the MCP directory API, please join our Discord server