README.md•4.98 kB
# MCP 服务器演示项目
一个基于 Model Context Protocol (MCP) 的多功能服务器演示项目，展示了如何构建和使用不同类型的 MCP 服务器。
## 🚀 项目概述
本项目是一个 monorepo，包含了三个不同功能的 MCP 服务器示例：
- **Database Search** - 智能数据库搜索服务，支持自然语言查询
- **GitHub Search** - GitHub 仓库和用户信息搜索服务
- **Time** - 时间获取和时区转换服务
所有服务器都基于 Model Context Protocol (MCP) 标准构建，可以与支持 MCP 的客户端（如 Claude Desktop）无缝集成。
## 📦 项目结构
```
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
### 安装依赖
```bash
# 克隆项目
git clone <repository-url>
cd hh-mcp-server
# 安装依赖
pnpm install
```
### 构建所有包
```bash
# 构建所有 MCP 服务器
pnpm run build
```
### 代码格式化
```bash
# 格式化代码
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
[查看详细文档](./packages/database-search/README.md)
### 2. GitHub Search MCP Server
**功能**: 搜索 GitHub 仓库、代码、问题和用户信息
**核心特性**:
- 🔍 全面搜索（仓库、代码、问题、用户）
- 📄 分页支持
- 🔑 GitHub API 集成
- 📊 结构化数据返回
**工具列表**:
- `search_github` - 搜索 GitHub 内容
- `get_user_info` - 获取用户详细信息
**使用示例**:
```bash
cd packages/github-search
# 设置 GitHub Token
export GITHUB_TOKEN=your_github_token
# 构建并运行
pnpm run build
node dist/index.js
```
**代码来源**:
[代码来源](https://github.com/vaebe/mcp)
### 3. Time MCP Server
**功能**: 获取当前时间和进行时区转换
**核心特性**:
- 🕐 获取当前时间
- 🌍 时区转换
- 🔧 灵活的时区配置
- 📅 标准时间格式
**工具列表**:
- `get_current_time` - 获取当前时间
- `convert_time` - 时区间时间转换
**使用示例**:
```bash
cd packages/time
# 构建并运行
pnpm run build
node dist/index.js
```
**代码来源**:
[代码来源](https://github.com/vaebe/mcp)
## 🔧 开发指南
### 添加新的 MCP 服务器
1. 在 `packages/` 目录下创建新包
2. 配置 `package.json` 和 `tsconfig.json`
3. 实现 MCP 服务器逻辑
4. 添加到 workspace 配置
### 项目脚本命令
```bash
# 构建所有包
pnpm run build
# 格式化代码
pnpm run format
# 检查代码格式
pnpm run format:check
# 运行测试（待实现）
pnpm run test
```
### 开发最佳实践
- 使用 TypeScript 进行类型安全
- 遵循 MCP 标准和最佳实践
- 使用 zod 进行参数验证
- 实现适当的错误处理
- 添加详细的工具描述和参数说明
## 🤝 与 MCP 客户端集成
### Claude Desktop 配置示例
在 Claude Desktop 的配置文件中添加服务器：
```json
{
"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）配合使用。