内容
# mcp-hugo-server-go
[](go.mod)
[](https://github.com/jmrGrav/mcp-hugo-server-go/releases/latest)
[](https://github.com/jmrGrav/mcp-hugo-server-go/actions/workflows/ci.yml)
[](LICENSE)
[](SECURITY.md)
[](https://modelcontextprotocol.io)
[](https://chatgpt.com/)
[](https://claude.ai)
[](https://isitagentready.com/www.arleo.eu)
Hugo 站点的规范统一 MCP 服务器。
公共端点：`https://mcp.arleo.eu/mcp`
## 功能描述
`mcp-hugo-server-go` 通过模型上下文协议公开 Hugo 站点，具有公共发现、OAuth 支持的范围和严格的读、写、管理、系统操作之间的隔离。
它是以下项目的统一继承者：
- `hugo-public-mcp` 用于公共发现、OAuth 和 `auth.md`
- `hugo-mcp-go` 用于内容和管理员工具
- `mcp-runtime-go` 用于 MCP 传输/运行时行为
## 范围模型
- `anonymous`：公共、安全的只读发现
- `content.read`：更丰富的只读访问
- `content.write`：创建、更新和删除操作
- `site.admin`：构建和站点管理操作
- `system.admin`：完整性和诊断操作
旧版客户端仍可以发送 `mcp` 作为范围。服务器接受它作为 `content.read` 的废弃兼容性别名。
## 工具清单
当前工具清单在 [docs/tools.md](docs/tools.md) 中有详细记录，应被视为范围映射和工具命名的真实来源。
## 安全模型
- 匿名调用者只能看到公共只读工具。
- 非公共层级需要 OAuth 承载令牌。
- `content.write`、`site.admin` 和 `system.admin` 永远不会暴露给匿名调用者。
- 旧版 `mcp` 别名被接受用于兼容性，但不作为规范进行宣传。
## Claude 和 MCP
Claude Desktop 和 Claude.ai 可以直接连接到上面的公共 MCP 端点。
服务器卡和 OAuth 发现仅宣传规范范围：
- `content.read`
- `content.write`
- `site.admin`
- `system.admin`
## 验证
存储库应通过：
```bash
go test ./...
go test -race ./...
go vet ./...
govulncheck ./...
gitleaks detect --no-banner --redact --source .
```
## 项目血统
- [hugo-public-mcp](https://github.com/jmrGrav/hugo-public-mcp) - 公共代理就绪发现、OAuth 和 `auth.md`
- [hugo-mcp-go](https://github.com/jmrGrav/hugo-mcp-go) - Hugo 内容和管理员工具
- [mcp-runtime-go](https://github.com/jmrGrav/mcp-runtime-go) - MCP 运行时和传输基础
`mcp-hugo-server-go` 是这些存储库的规范统一继承者。
## 架构
```
mcp.arleo.eu
├── anonymous 公共发现和安全的只读工具
├── content.read 更丰富的只读内容访问
├── content.write 内容创建和编辑
├── site.admin 构建和站点操作
└── system.admin 诊断和完整性检查
```
MCP 传输是 `/mcp` 处的流式 HTTP。
## 安全联系方式
要报告漏洞，请在服务器配置中设置 `security_contact`（例如，`security_contact: "mailto:security@example.com"`）。这会根据 RFC 9116 填充 `/.well-known/security.txt`。服务器需要 `Contact` 和 `Expires` — Canonical 会根据 `site_url`（或 `oauth.issuer` 如果 `site_url` 为空）自动设置。
## 代理身份流程
代理通过 `/agent/identity/verify` 类似设备流的端点进行身份验证：
1. 代理将 `{"type":"anonymous"}` 发送到 `/agent/identity` → 接收 `claim_token` + `verification_uri`。
2. 代理将 `claim_token` 发送到 `/agent/identity/claim` → 启动声明。
3. 操作员访问 `verification_uri`（或将 `claim_token` 发送到 `/agent/identity/verify`）并使用 `site.admin`/`system.admin` 持有者令牌来批准。
4. 代理在 `/token` 处交换其 `identity_assertion`（`grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer`）→ 接收 `content.read` 持有者令牌。
发送到 `/agent/identity/verify` 的 POST 请求需要操作员通过 `Authorization: Bearer <admin-token>` 头（或浏览器提交的 `admin_token` 表单字段）进行身份验证。
## API 参考
| 端点 | 方法 | 描述 |
|---|---|---|
| `/mcp` | GET/POST/DELETE | MCP 流式 HTTP 传输 |
| `/.well-known/oauth-authorization-server` | GET | OAuth 2.0 授权服务器元数据（RFC 8414） |
| `/.well-known/oauth-protected-resource` | GET | 受保护资源元数据（RFC 9728） |
| `/.well-known/mcp/server-card.json` | GET | MCP 服务器卡 |
| `/.well-known/mcp.json` | GET | MCP 服务器卡（别名） |
| `/.well-known/agent.json` | GET | 代理卡（Google A2A 模式） |
| `/.well-known/security.txt` | GET | 安全联系方式（RFC 9116） |
| `/robots.txt` | GET | 机器人排除 |
| `/llms.txt` | GET | LLM 发现 |
| `/auth.md` | GET | 身份验证指南 |
| `/metrics` | GET | Prometheus 指标 |
| `/register` | POST | OAuth 动态客户端注册 |
| `/authorize` | GET/POST | OAuth 授权端点 |
| `/token` | POST | OAuth 令牌端点 |
| `/agent/identity` | POST | 注册代理身份 |
| `/agent/identity/claim` | POST | 启动代理声明 |
| `/agent/identity/verify` | GET/POST | 操作员代理审批页面 |
| `/agent/event/notify` | POST | 代理事件通知 |
## 文档
- [操作员指南](docs/operator-guide.md)
- [工具清单](docs/tools.md)
- [安全政策](SECURITY.md)
