内容
<!-- hapax-sdlc:preamble:begin -->
# hapax-mcp
`hapax-mcp` 是一个用于Hapax系统组合的集成桥接器。它主要用于MCP集成和检查，而不是作为一个通用的框架。
## 阅读承诺
MCP桥接器暴露Hapax标志的API状态和动作给Claude Code和兼容的MCP客户端。
## 阅读价值
为MCP客户端提供一个有界的桥接器，以访问实时的Hapax状态，同时将权限保留在底层API中，而不是连接器中。
## 声称上限
仅作为集成桥接器；不是一个通用的MCP框架，也不是底层Hapax API之外的权限源。
## 许可证和权利
允许MCP使用的集成桥接器；当前副本必须将其框架为Hapax标志桥接器，而不是通用的MCP库。
渲染摘要：MIT。参见`LICENSE`、`NOTICE.md`、`CITATION.cff`和`.zenodo.json`以获取权限表面。
## 公共边界
- 问题仅限重定向；不接受讨论，不接受拉取请求；请参阅`CONTRIBUTING.md`和`SUPPORT.md`
- 公共副本必须使用`hapax-systems`组织的链接作为第一方Hapax仓库。
- 发布、博客、RSS、社交、DOI/存档和其他公共分发路径必须通过受控的发布总线或文档化的保护遗留表面进行路由。
- 治理参考：https://github.com/hapax-systems/hapax-constitution
## 投资组合定位
MCP桥接器。通过HTTP使用委员会和公务标志API，并为Claude Code和兼容的MCP客户端提供有界工具。权限保留在底层Hapax API中。
<!-- hapax-sdlc:preamble:end -->
## 描述
模型上下文协议服务器（FastMCP，stdio传输），它将Hapax标志的HTTP API作为MCP工具公开。默认端点是委员会标志API，位于`http://localhost:8051/api`。将`LOGOS_BASE_URL`指向`http://localhost:8050/api`，则会暴露公务标志API。
相同的标志数据可以通过三个独立的界面访问：hapax-logos Tauri应用程序、VS Code扩展（位于[hapax-council](https://github.com/hapax-systems/hapax-council)和[hapax-officium](https://github.com/hapax-systems/hapax-officium)）以及此MCP服务器。界面选择由操作员决定；能力在所有界面中相同。权限保留在标志API中；此仓库是桥接器，而不是策略源。
## 工具表面（38种工具）
| 组 | 计数 | 工具 | 阅读价值 |
|-------|-------|-------|---|
| 只读 | 22 | health, health_history, briefing, scout, scout_decisions, drift, cost, goals, nudges, agents, gpu, infrastructure, profile, profile_dimension, profile_pending, accommodations, copilot, readiness, workspace, manual, working_mode, cycle_mode | 为MCP客户端提供可见性到状态，而无需拥有底层API。 |
| 年鉴 | 2 | chronicle, chronicle_narrate | 允许客户端检查和总结事件历史，源窗口明确。 |
| 写入 | 10 | nudge_act, nudge_dismiss, working_mode_set, cycle_mode_set, profile_correct, profile_delete, profile_flush, scout_decide, accommodation_confirm, accommodation_disable | 暴露有界动作，服务器端Hapax API保持权威。 |
| 流式（SSE） | 2 | query, query_refine | 承载长期查询/精炼流程，不会将MCP桥接器变成规划器。 |
| 复合 | 2 | status (health + gpu + infrastructure + working_mode), daily_summary (briefing + nudges + goals + drift) | 为操作员提供总结，不需要客户端重建常见视图。 |
`working_mode`和`working_mode_set`是规范的。`cycle_mode`和`cycle_mode_set`是废弃的别名，在工作区范围内的迁移期间保留；两者都通过服务器端路由到`/working-mode`。接受的模式值：`research`、`rnd`、`fortress`（officium省略`fortress`）。遗留的`dev`/`prod`值在服务器端返回422。
`chronicle`接受过滤器`since`、`until`、`source`、`event_type`、`trace_id`、`limit`。`chronicle_narrate`生成chronicle窗口的LLM综合。
## 安装
```bash
uv sync
uv run hapax-mcp
```
Python 3.12+。依赖项：`mcp>=1.26`、`httpx>=0.28.1`、`pydantic>=2.0`。入口点：`hapax_mcp.server:main`（在`pyproject.toml`中定义）。
## 在Claude Code中注册
添加到`~/.claude/settings.json`下的`mcpServers`：
```json
{
"mcpServers": {
"hapax": {
"command": "uv",
"args": ["--directory", "/path/to/hapax-mcp", "run", "hapax-mcp"],
"env": {
"LOGOS_BASE_URL": "http://localhost:8051/api"
}
}
}
}
```
要桥接officium API，还可以注册第二个实例，设置`LOGOS_BASE_URL=http://localhost:8050/api`。
## 配置
| 变量 | 默认值 | 目的 |
|----------|---------|---------|
| `LOGOS_BASE_URL` | `http://localhost:8051/api` | 标志API基准URL |
| `LOGOS_API_KEY` | 未设置 | 可选的承载令牌；如果设置，则作为`Authorization: Bearer …`发送 |
| `COCKPIT_BASE_URL` | 未设置 | `LOGOS_BASE_URL`的向后兼容性备用 |
| `COCKPIT_API_KEY` | 未设置 | `LOGOS_API_KEY`的向后兼容性备用 |
HTTP超时：标准请求为15秒；SSE流总共为120秒；每个事件超时30秒，超时流中止。响应正文在50,000个字符处被截断；SSE流在1,000个块或1 MiB总量处被截断。工具接受的路径段根据`[a-zA-Z0-9_-]+`进行验证。
错误被捕获并格式化为用户可见的字符串，通过`_fmt_error()`；在MCP边界处不引发异常。
## 项目布局
```
src/hapax_mcp/
server.py MCP服务器，38种工具定义
client.py HTTP客户端，环境变量合约，超时
models/ Pydantic响应模型（health, infrastructure, profile, working_mode）
tests/ pytest套件（test_tools.py, test_response_models.py）
pyproject.toml 包元数据，入口点，依赖项
```
服务器发出静态指令警告，工具输出可能包含来自外部源的内容，不应视为指令。这与上游章程中的`interpersonal_transparency`公理一致。
## CI
| 工作流 | 触发器 | 效果 |
|----------|---------|--------|
| `ci.yml` | 推送主分支，PR | ruff检查 + 格式化，pyright，gitleaks，bandit |
| `auto-fix.yml` | PR上的CI失败 | Claude Code尝试修复；每个分支最多3次尝试 |
| `claude-review.yml` | PR打开/同步 | PR上的Claude Code审查 |
| `dependabot-auto-merge.yml` | Dependabot PR | 自动合并补丁/小版本升级 |
## 相关仓库
| 仓库 | 角色 |
|-----------|------|
| [hapax-council](https://github.com/hapax-systems/hapax-council) | 主要研究成果 — 语音守护进程，基础系统，实验基础设施 |
| [hapax-constitution](https://github.com/hapax-systems/hapax-constitution) | 治理规范 — 公理，影响，准则，先例 |
| [hapax-officium](https://github.com/hapax-systems/hapax-officium) | 支持软件 — 管理决策支持 |
| [hapax-watch](https://github.com/hapax-systems/hapax-watch) | Wear OS生物识别伴侣 |
| [hapax-phone](https://github.com/hapax-systems/hapax-phone) | Android健康 + 上下文伴侣 |
| **hapax-mcp**（此仓库） | MCP服务器，桥接标志API到Claude Code |
## 许可证
MIT — 参见[LICENSE](LICENSE)。
