Skip to main content
Glama
CH-122

MCP Server Demo

by CH-122
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Hybrid

MCP 服务器演示项目

一个基于 Model Context Protocol (MCP) 的多功能服务器演示项目，展示了如何构建和使用不同类型的 MCP 服务器。

🚀 项目概述

本项目是一个 monorepo，包含了三个不同功能的 MCP 服务器示例：

  • Database Search - 智能数据库搜索服务，支持自然语言查询

  • GitHub Search - GitHub 仓库和用户信息搜索服务

  • Time - 时间获取和时区转换服务

所有服务器都基于 Model Context Protocol (MCP) 标准构建，可以与支持 MCP 的客户端（如 Claude Desktop）无缝集成。

Related MCP server: MCP Toolkit

📦 项目结构

hh-mcp-server/
├── packages/
│   ├── database-search/     # 数据库搜索 MCP 服务器
│   ├── github-search/       # GitHub 搜索 MCP 服务器
│   └── time/               # 时间服务 MCP 服务器
├── package.json            # 根项目配置
├── pnpm-workspace.yaml     # pnpm workspace 配置
└── README.md              # 项目说明文档

🛠️ 技术栈

  • 运行时: Node.js + TypeScript

  • 包管理: pnpm workspace

  • 框架: Model Context Protocol SDK

  • 数据库: MySQL, PostgreSQL, SQLite (database-search)

  • API: GitHub API (github-search)

  • 工具库: dayjs, zod, prettier

🚀 快速开始

环境要求

  • Node.js >= 18

  • pnpm >= 8

安装依赖

# 克隆项目
git clone <repository-url>
cd hh-mcp-server

# 安装依赖
pnpm install

构建所有包

# 构建所有 MCP 服务器
pnpm run build

代码格式化

# 格式化代码
pnpm run format

# 检查代码格式
pnpm run format:check

📚 MCP 服务器详解

1. Database Search MCP Server

功能: 支持自然语言查询多种数据库，提供智能 SQL 转换

核心特性:

  • 🗄️ 多数据库支持（MySQL、PostgreSQL、SQLite）

  • 🧠 自然语言转 SQL（基于 OpenAI GPT）

  • 🔒 安全 SQL 检查和过滤

  • ⚙️ 灵活的环境配置管理

  • 🔄 连接池和资源管理

工具列表:

  • query_database - 自然语言数据库查询

  • list_databases - 列出可用数据库

  • get_table_structure - 获取表结构

  • execute_sql - 直接执行 SQL

查看详细文档

2. GitHub Search MCP Server

功能: 搜索 GitHub 仓库、代码、问题和用户信息

核心特性:

  • 🔍 全面搜索（仓库、代码、问题、用户）

  • 📄 分页支持

  • 🔑 GitHub API 集成

  • 📊 结构化数据返回

工具列表:

  • search_github - 搜索 GitHub 内容

  • get_user_info - 获取用户详细信息

使用示例:

cd packages/github-search

# 设置 GitHub Token
export GITHUB_TOKEN=your_github_token

# 构建并运行
pnpm run build
node dist/index.js

代码来源:

代码来源

3. Time MCP Server

功能: 获取当前时间和进行时区转换

核心特性:

  • 🕐 获取当前时间

  • 🌍 时区转换

  • 🔧 灵活的时区配置

  • 📅 标准时间格式

工具列表:

  • get_current_time - 获取当前时间

  • convert_time - 时区间时间转换

使用示例:

cd packages/time

# 构建并运行
pnpm run build
node dist/index.js

代码来源:

代码来源

🔧 开发指南

添加新的 MCP 服务器

  1. 在 packages/ 目录下创建新包

  2. 配置 package.json 和 tsconfig.json

  3. 实现 MCP 服务器逻辑

  4. 添加到 workspace 配置

项目脚本命令

# 构建所有包
pnpm run build

# 格式化代码
pnpm run format

# 检查代码格式
pnpm run format:check

# 运行测试（待实现）
pnpm run test

开发最佳实践

  • 使用 TypeScript 进行类型安全

  • 遵循 MCP 标准和最佳实践

  • 使用 zod 进行参数验证

  • 实现适当的错误处理

  • 添加详细的工具描述和参数说明

🤝 与 MCP 客户端集成

Claude Desktop 配置示例

在 Claude Desktop 的配置文件中添加服务器：

{
  "mcpServers": {
    "database-search": {
      "command": "node",
      "args": ["path/to/packages/database-search/dist/index.js"],
      "env": {
        "NODE_ENV": "production"
      }
    },
    "github-search": {
      "command": "node",
      "args": ["path/to/packages/github-search/dist/index.js"],
      "env": {
        "GITHUB_TOKEN": "your_token"
      }
    },
    "time": {
      "command": "node",
      "args": ["path/to/packages/time/dist/index.js"]
    }
  }
}

📄 许可证

ISC License

🤝 贡献

欢迎提交 Issue 和 Pull Request！

📞 支持

如果您在使用过程中遇到问题，请：

  1. 查看各包的详细文档

  2. 检查环境配置

  3. 提交 Issue 描述问题

注意: 这些是 MCP (Model Context Protocol) 服务器，需要与支持 MCP 的客户端（如 Claude Desktop）配合使用。

Available Tools

2 tools
get_current_dateB

获取当前日期, 如果用户没有提供日期, 则返回当前日期, 如果用户提供的是相对单位, 如前天, 昨天, 明天, 则返回相对单位后的日期

ParametersJSON Schema
NameRequiredDescriptionDefault
dateYes日期 比如2025-05-29 或者 前天 昨天 明天

TDQS

B3.1/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 full burden. It describes the core behavior (returning current date or calculating relative dates) but lacks important details: format of returned date, timezone handling, error behavior for invalid inputs, or whether this is a read-only operation. The description doesn't disclose these behavioral traits.

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 appropriately concise with two sentences that efficiently explain the tool's functionality. It's front-loaded with the main purpose and follows with usage details. There's no wasted text, though it could be slightly more structured for clarity.

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 has no annotations and no output schema, the description is incomplete. It doesn't explain the return format (e.g., date string structure), error handling, or timezone considerations. For a date-handling tool with 1 parameter, more contextual details are needed to ensure proper agent usage.

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%, with the parameter 'date' clearly documented in the schema. The description adds some semantic context by explaining the two types of inputs (absolute dates like 2025-05-29 and relative units like yesterday), which complements the schema. However, it doesn't provide additional syntax or format details beyond what the schema already states.

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 date) and explains it returns the current date or calculates relative dates like yesterday/tomorrow. It distinguishes from sibling 'get_current_weather' by focusing on dates rather than weather. However, it doesn't explicitly contrast with the sibling tool in the description text itself.

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

Usage Guidelines3/5

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

The description implies usage context: when users need current date or relative date calculations. It mentions handling both absolute dates (e.g., 2025-05-29) and relative units (e.g., yesterday). However, it doesn't provide explicit guidance on when to use this vs. alternatives or any exclusion criteria.

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

get_current_weatherC

Get weather info for a given city.

ParametersJSON Schema
NameRequiredDescriptionDefault
cityYes城市名称, 比如北京 上海 广州

TDQS

C2.9/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. It mentions 'Get weather info' which implies a read-only operation, but doesn't disclose any behavioral traits like rate limits, error conditions, data freshness, or what 'weather info' includes (e.g., temperature, humidity). This leaves significant gaps for an agent.

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 with zero waste. It's front-loaded with the core action and resource, making it easy to parse quickly without unnecessary elaboration.

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 no annotations and no output schema, the description is incomplete. It doesn't explain what 'weather info' includes, potential errors, or any operational constraints. For a tool with one parameter but undefined output and behavior, this leaves too much ambiguity for reliable agent use.

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%, with the parameter 'city' fully documented in the schema. The description adds no additional meaning beyond implying the tool requires a city input, so it meets the baseline of 3 where the schema does the heavy lifting.

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 verb ('Get') and resource ('weather info') with a specific scope ('for a given city'), making the purpose unambiguous. However, it doesn't explicitly differentiate from the sibling tool 'get_current_date', though the distinction is obvious from the names.

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?

No guidance is provided on when to use this tool versus alternatives or any contextual prerequisites. The description simply states what it does without indicating any constraints, dependencies, or comparison with the sibling tool beyond the obvious domain difference.

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. 2 tool updates
    • First observedget_current_date
    • First observedget_current_weather
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

B3.1/5.0

Scored across 2 tools

Disambiguation5/5

The two tools have completely distinct purposes: one handles date calculations and retrieval, while the other provides weather information. There is no overlap in functionality, making it impossible to confuse them.

Naming Consistency5/5

Both tools follow a consistent 'get_current_*' naming pattern, using snake_case and starting with the same verb 'get'. This makes the set predictable and easy to understand.

Tool Count2/5

With only two tools, the server feels thin and under-scoped for a general-purpose demo. It lacks coverage for common tasks beyond dates and weather, suggesting an incomplete or narrowly focused implementation.

Completeness2/5

The server's domain appears to be general utility or information retrieval, but it only covers dates and weather. There are significant gaps, such as time, location, or other common data queries, leaving agents with limited functionality.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • mcp

    alokverma18
    A
    license
    Not graded
    quality
    D
    maintenance
    Provides MCP servers for GitHub API operations and SQL database queries, enabling users to interact with GitHub repositories and databases through natural language.
    3
    MIT

  • MCP Toolkit

    fastprosecurity
    A
    license
    Not graded
    quality
    F
    maintenance
    A collection of production-ready MCP servers for PostgreSQL, SQLite, Redis, File System, and GitHub API, enabling database operations, file management, and GitHub interactions through natural language.
    2
    MIT
  • Manifest MCP by manifest-network

    Manifest MCPofficial

    manifest-network
    A
    license
    Not graded
    quality
    A
    maintenance
    A monorepo of MCP servers for Manifest Network and Cosmos SDK chains, enabling natural language interaction with on-chain queries, transactions, lease operations, and provider management.
    MIT