内容
# hex-mcp
一款遵循MIT许可的MCP服务器，通过官方Hex公共API规范生成。
服务器在启动时加载Hex当前的OpenAPI文档，并通过FastMCP将其操作作为确定的、snake_case的MCP工具公开。
PyPI分发和安装命令名为`hex-openapi-mcp`。较短的`hex-mcp`命令仍然可用，Python导入为`hex_mcp`。
## 功能模式
- `read-only` 仅公开被分类为非变异的操作，无论配置的Hex令牌的权限如何。
- `full` 公开完整的官方API表面。
`read-only` 是默认模式。它注册GET操作和非变异的`export_project` POST操作。在此模式下，即使`HEX_API_TOKEN`具有写入权限，变异工具也不会在MCP目录中存在。
## 安装
要求：Python 3.12 或更新版本 和 [uv](https://docs.astral.sh/uv/)。
直接从 PyPI 运行服务器：
```bash
HEX_API_TOKEN=your_hex_token uvx hex-openapi-mcp
```
显式启用完整的API表面：
```bash
HEX_API_TOKEN=your_hex_token HEX_MCP_MODE=full uvx hex-openapi-mcp
```
默认传输方式是stdio。要运行可流式HTTP：
```bash
HEX_API_TOKEN=your_hex_token HEX_TRANSPORT=http uvx hex-openapi-mcp
```
默认监听地址是 `http://127.0.0.1:8000/mcp`。
## 从源码运行
要求：Python 3.12 或更新版本 和 [uv](https://docs.astral.sh/uv/)。
```bash
uv sync --locked --dev
HEX_API_TOKEN=your_hex_token uv run hex-openapi-mcp
```
## MCP 客户端配置
从 PyPI：
```json
{
"mcpServers": {
"hex": {
"command": "uvx",
"args": ["hex-openapi-mcp"],
"env": {
"HEX_API_TOKEN": "your_hex_token",
"HEX_MCP_MODE": "read-only"
}
}
}
}
```
对于本地检出，使用 `"command": "uv"` 和 `"args": ["--directory", "/absolute/path/to/hex-mcp", "run", "hex-openapi-mcp"]`.
对于stdio，MCP客户端仅将`HEX_API_TOKEN`传递给子进程。不要将令牌放在命令行参数中。
## 配置
| 变量 | 默认值 | 目的 |
| --- | --- | --- |
| `HEX_API_TOKEN` | 必需 | Hex个人或工作区 bearer token |
| `HEX_MCP_MODE` | `read-only` | `read-only` 或 `full` 工具目录 |
| `HEX_API_BASE_URL` | `https://app.hex.tech/api` | Hex API基准URL |
| `HEX_OPENAPI_SPEC` | `https://static.hex.site/openapi.json` | 官方规范URL或本地JSON文件 |
| `HEX_TRANSPORT` | `stdio` | `stdio` 或 `http` |
| `HEX_HTTP_HOST` | `127.0.0.1` | 流式HTTP绑定主机 |
| `HEX_HTTP_PORT` | `8000` | 流式HTTP绑定端口 |
| `HEX_HTTP_PATH` | `/mcp` | 流式HTTP端点路径 |
| `HEX_REQUEST_TIMEOUT_SECONDS` | `30` | 规范下载和Hex API超时 |
## 开发
```bash
uv run ruff format --check .
uv run ruff check .
uv run mypy
uv run pytest
```
存储库不包含Hex的规范。通过设置`HEX_OPENAPI_SPEC`为独立提供的本地副本，可以离线测试合约行为。
## 安全性和可靠性
- 每个工具都具有从其官方操作和HTTP方法派生的MCP只读、破坏性、幂等和开放世界注释。
- 工具结果和Hex错误主体在到达MCP输出或错误日志记录之前，会递归地编辑已知的凭据字段和Hex bearer令牌。
- Hex HTTP错误在结构化的MCP错误中保留状态、原因和跟踪ID，而不暴露内部堆栈跟踪。
- GET请求重试瞬时的`429`、`502`、`503`和`504`响应，最多重试两次，尊重`Retry-After`，并使用有界指数退避。写入请求永远不会自动重试。
Hex的规范当前发布了两个语义路径，带有后端正则表达式语法作为字面OpenAPI路径。这些字面路径返回`404`，而两个扩展路由都存在。加载器在生成工具之前会将它们规范化为当前的`/v1/semantic-projects/...`命名，同时保留原始规范摘要以进行可观察性。
流式HTTP当前使用单个服务器范围的`HEX_API_TOKEN`，并且没有传入客户端身份验证。除非访问受到受信任的身份验证代理的保护，否则请保留默认的环回绑定。
## 设计文档
- [功能矩阵](docs/capability-matrix.md)
- [实现计划](docs/implementation-plan.md)
- [发布流程](docs/releasing.md)
