内容
# 门户 MCP
门户 MCP 是一个模型上下文协议（MCP）服务器，用于将 AI 客户端（如 Cursor 或 MCP Inspector）连接到您的门户后端 API。
它将门户操作作为 MCP 工具公开，并向模型返回安全、结构化的数据。
## 本项目的作用
- 在 `/mcp` 上运行 MCP 服务器
- 使用 Bearer 身份验证保护请求
- 为门户数据访问提供 MCP 工具
- 在返回 API 响应之前进行验证和转换
- 将 HTTP 客户端逻辑保留在可重用的实用函数中
## 当前工具
- `echo`: 返回相同的消息（健康检查和测试）
- `get-user-info`: 从内部门户 API 获取身份验证的用户配置文件
## 技术栈
- Bun + TypeScript
- Express
- `@modelcontextprotocol/*` 包
- Axios
- Zod
## 项目结构
- `index.ts`: HTTP 应用引导和 MCP 路由
- `server/index.ts`: MCP 服务器创建和注册
- `tools/`: MCP 工具
- `utils/axios.ts`: API 客户端助手和错误处理
- `types/`: 共享 TypeScript 类型
- `domains/`: 进行中的领域优先结构（cartable 模块）
## 环境变量
复制 `.env.example` 到 `.env` 并设置值：
```env
PORT=8080
PORTAL_MCP_TOKEN=您的令牌
PORTAL_API_URL=http://localhost:3001
REMOTE_PORTAL_API_URL=https://portal.hamgam-khodro.com:8089/api/
```
## 快速开始（简单）
1. 安装依赖：
```bash
bun install
```
2. 启动服务器：
```bash
bun run dev
```
3. 服务器可在以下地址访问：
`http://localhost:8080/mcp`
4. 在 MCP Inspector 中测试：
```bash
bun run inspect
```
使用 Streamable HTTP 传输，URL 为 `http://localhost:8080/mcp`，并发送：
`Authorization: Bearer <PORTAL_MCP_TOKEN>`
## Cursor 配置说明
对于 HTTP MCP 服务器，Cursor 从操作系统环境变量中读取 `${env:...}`，而不是从项目 `.env` 中。
如果您在 `.cursor/mcp.json` 中使用此配置：
```json
{
"mcpServers": {
"portal-mcp": {
"url": "http://localhost:8080/mcp",
"headers": {
"Authorization": "Bearer ${env:PORTAL_MCP_TOKEN}"
}
}
}
}
```
请确保 `PORTAL_MCP_TOKEN` 已在您的系统/用户环境中设置，并重启 Cursor。
