README.md•5.33 kB
# MCP Server - 模块化多工具服务
> **English below 中文介绍**
---
## 📝 项目简介
MCP Server 是基于 Model Context Protocol (MCP) 的模块化服务端，支持天气、定位、数学计算、IoT 设备控制、GitHub 搜索等多种工具，适合智能体/AI 助手等场景。
## 📁 目录结构
```
├── src/
│ ├── app.ts # 应用主类
│ ├── index.ts # 启动入口
│ ├── config/ # 配置
│ ├── types/ # 类型定义
│ ├── middleware/ # 中间件
│ ├── routes/ # 路由
│ ├── services/ # 业务服务
│ ├── tools/ # 工具函数（天气、定位、计算、IoT、搜索等）
│ └── utils/ # 通用工具
├── test/ # 测试脚本
├── package.json # 依赖与脚本
├── tsconfig.json # TypeScript 配置
└── ...
```
## 🚀 快速开始
### 安装依赖
```bash
npm install
```
### 启动开发环境
```bash
npm run dev
```
### 生产环境
```bash
npm run build
npm run start:prod
```
### 其他命令
```bash
npm run dev:watch # nodemon 热重载
npm run dev:debug # 调试模式
npm start # 直接运行（ts-node）
```
## ⚙️ 配置
- 端口、名称、版本、日志、会话等均可通过环境变量配置，详见 `src/config/index.ts`
- 常用环境变量：
- `PORT`、`SERVER_NAME`、`SERVER_VERSION`、`NODE_ENV`、`LOG_LEVEL`、`MAX_SESSIONS`、`SESSION_TIMEOUT`
## 🔧 可用工具（API）
### 1. 天气查询 getWeather
- 参数：`city`（可选，城市名，缺省自动定位），`unit`（可选，celsius/fahrenheit）
- 示例：
```json
{ "city": "北京", "unit": "celsius" }
```
### 2. 定位 getLocation
- 参数：无
- 返回：当前定位的城市名（模拟/可扩展）
### 3. 数学计算 calculate
- 参数：`operation`（add/subtract/multiply/divide），`a`，`b`
- 示例：
```json
{ "operation": "add", "a": 1, "b": 2 }
```
### 4. IoT 设备控制 iotControl
- 参数：`deviceId`，`action`（lock/unlock/open/close/getStatus），`value`（可选）
- 示例：
```json
{ "deviceId": "lock001", "action": "lock" }
```
### 5. GitHub 搜索 search
- 参数：`query`（关键词），可选：`language`、`stars`、`forks`、`user`、`topic`、`created`、`sort`、`order`、`limit`
- 示例：
```json
{ "query": "nodejs", "language": "TypeScript", "limit": 3 }
```
## 📊 健康检查
- `GET /health` 返回服务器状态
## 🧪 测试
所有测试脚本位于 `test/` 目录：
- `test/test-mcp.js`、`test/test-modular.js`、`test/test-tools-rename.js`
- 运行示例：
```bash
node test/test-mcp.js
node test/test-modular.js
node test/test-tools-rename.js
```
## 🔄 扩展指引
- 新增工具：在 `src/tools/` 新建文件并注册
- 新增服务/中间件/类型：参考现有目录结构
## 📝 许可证
ISC
---
# MCP Server - Modular Multi-Tool Service (English)
## 📝 Introduction
MCP Server is a modular backend based on Model Context Protocol (MCP), supporting weather, location, calculator, IoT device control, GitHub search and more. Ideal for AI agents and assistant scenarios.
## 📁 Structure
See above for directory tree. Main code in `src/`, tests in `test/`.
## 🚀 Quick Start
### Install dependencies
```bash
npm install
```
### Start development server
```bash
npm run dev
```
### Production
```bash
npm run build
npm run start:prod
```
### Other scripts
```bash
npm run dev:watch # nodemon hot reload
npm run dev:debug # debug mode
npm start # direct run (ts-node)
```
## ⚙️ Configuration
- All configs (port, name, version, log, session, etc.) via env vars, see `src/config/index.ts`
- Common env vars: `PORT`, `SERVER_NAME`, `SERVER_VERSION`, `NODE_ENV`, `LOG_LEVEL`, `MAX_SESSIONS`, `SESSION_TIMEOUT`
## 🔧 Tools (APIs)
### 1. Weather getWeather
- Params: `city` (optional, auto-location if omitted), `unit` (optional, celsius/fahrenheit)
- Example:
```json
{ "city": "Beijing", "unit": "celsius" }
```
### 2. Location getLocation
- Params: none
- Returns: current city (mocked/extendable)
### 3. Calculator calculate
- Params: `operation` (add/subtract/multiply/divide), `a`, `b`
- Example:
```json
{ "operation": "add", "a": 1, "b": 2 }
```
### 4. IoT Device Control iotControl
- Params: `deviceId`, `action` (lock/unlock/open/close/getStatus), `value` (optional)
- Example:
```json
{ "deviceId": "lock001", "action": "lock" }
```
### 5. GitHub Search search
- Params: `query` (keyword), optional: `language`, `stars`, `forks`, `user`, `topic`, `created`, `sort`, `order`, `limit`
- Example:
```json
{ "query": "nodejs", "language": "TypeScript", "limit": 3 }
```
## 📊 Health Check
- `GET /health` returns server status
## 🧪 Testing
All test scripts in `test/`:
- `test/test-mcp.js`, `test/test-modular.js`, `test/test-tools-rename.js`
- Run example:
```bash
node test/test-mcp.js
node test/test-modular.js
node test/test-tools-rename.js
```
## 🔄 Extension
- Add tool: create file in `src/tools/` and register
- Add service/middleware/type: follow existing structure
## 📝 License
ISC