内容
# mcp-gen-ui-gateway
<p align="center">
<img src="docs/assets/banner.png" alt="mcp-gen-ui-gateway banner" width="720" />
</p>
<p align="center">
<a href="https://github.com/orca-svg/mcp-gateway-genui/actions/workflows/ci.yml"><img src="https://github.com/orca-svg/mcp-gateway-genui/actions/workflows/ci.yml/badge.svg" alt="持续集成状态"></a>
<a href="https://github.com/orca-svg/mcp-gateway-genui/actions/workflows/canary.yml"><img src="https://github.com/orca-svg/mcp-gateway-genui/actions/workflows/canary.yml/badge.svg" alt="Canary（实时 API）"></a>
<a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-blue.svg" alt="许可证：Apache-2.0"></a>
<img src="https://img.shields.io/badge/node-%3E%3D22.5.0-339933.svg" alt="Node >= 22.5.0">
<a href="CONTRIBUTING.md"><img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg" alt="欢迎 PR"></a>
</p>
开源 **公共利益发现的 MCP 网关** 和 Gen UI 渲染。
它通过确定性的 MCP 工具公开韩国公共利益数据，并将结构化的 JSON 响应渲染为紧凑的 UI。服务器是 **LLM-free** 的 —— MCP 主机模型处理对话并决定调用哪些工具。
> **状态：** G-4 操作信任发布线。该存储库是原始 [KOI 竞争项目](https://github.com/koi2026/mcp-gen-ui-gateway) 的干净室重新实现和继续维护，仅用作规范（PRD、模式定义、主机提示）。参见 `NOTICE`。
## 目录
- [快速开始](#快速开始)
- [为什么](#为什么)
- [架构](#架构)
- [公共 API](#公共-api)
- [工具](#工具)
- [安全边界](#安全边界)
- [文档](#文档)
- [许可证](#许可证)
## 快速开始
需要 **Node.js >= 22.5** （使用内置的 `node:sqlite`）和 pnpm。
```bash
pnpm install
pnpm build # 构建工作区包
pnpm typecheck
pnpm test
```
单独运行各个部分：
```bash
pnpm dev # 演示 UI（Vite）
pnpm mcp # stdio MCP 服务器
pnpm schemas # 从 Zod 重新导出 JSON 模式
```
### 从主机使用 MCP 服务器
服务器通过 stdio 进行 MCP。 将 MCP 主机指向构建的二进制文件：
```json
{
"mcpServers": {
"mcp-gen-ui-gateway": {
"command": "node",
"args": ["packages/mcp-server/dist/index.js"],
"env": {
"MCP_GEN_UI_REPOSITORY_MODE": "fixture",
"MCP_GEN_UI_DB_PATH": "mcp-gen-ui-gateway.db"
}
}
}
}
```
参见 `docs/host-prompts.md` 获取推荐的主机提示和示例流程。
## 为什么
公共利益信息分散在政府页面上，资格规则难以比较。此网关在稳定的 JSON 契约后面标准化这些数据，以便任何 MCP 主机都可以：
- 根据非识别性个人资料条件搜索利益
- 区分 **`candidate` / `needs_more_info` / `conflict_detected`** 评估
- 查看 **原因** 和 **仍需验证的条件**
- 获取 **准备检查清单** 和 **仅用户操作的应用指南**
它从不存储敏感标识符，从不声称确定资格，从不自动登录或提交。
建议是候选资格，而不是资格决定，用户必须在官方来源上验证最终要求。
## 架构
```
主机（任何 MCP 客户端）
└─ MCP 工具调用 ─▶ 利益工具服务 （packages/core）
├─ 源感知读取存储库（fixture/live/mixed）
├─ 评估（仅结构化约束的硬冲突）
└─ 相对相关性排名（基于规则，LLM-free）
└─ 严格的 v2 JSON ─▶ Gen UI / A2UI 消费者
源适配器 ─▶ 利益摄取服务 ─▶ 快照存储（显式写入路径）
```
### 单体仓库布局
| 包 | 责任 |
| --- | --- |
| `@mcp-gen-ui/schema` | Zod 模式作为单一真实来源；导出 JSON 模式。 |
| `@mcp-gen-ui/core` | 存储库、基于规则的推荐器、SQLite 快照/变更日志、插件一致性规则、传输中立的 `BenefitToolService`。 |
| `@mcp-gen-ui/adapters` | 复合/缓存存储库包装器和实时韩国公共利益数据适配器。 |
| `@mcp-gen-ui/mcp-server` | stdio MCP 服务器，注册网关工具。 |
| `@mcp-gen-ui/demo-ui` | Vite + React 渲染器；通过 A2UI 适配器映射固定域 JSON。 |
## 公共 API
发布的 npm 界面故意很小，以便嵌入者可以在不承担演示应用或存储库内部的情况下依赖网关：
| 包 | 公共契约 |
| --- | --- |
| `@mcp-gen-ui/schema` | 严格的 Zod 4 契约和 2020-12 草案 JSON 模式，用于所有七种 v2 工具，以及代表性契约状态的版本化固定值。 |
| `@mcp-gen-ui/core` | 源感知的读取存储库、评估/排名、显式摄取、原子 SQLite 快照/更改历史和 `BenefitToolService`。 |
| `@mcp-gen-ui/adapters` | 可选的 `BenefitRepository` 实现，用于扇入、TTL 缓存和实时온통청년 · 복지로 · 기획예산처 국고보조금 공모사업 数据。 |
| `@mcp-gen-ui/mcp-server` | 暴露网关工具的 stdio MCP 服务器，包括角色预设发现和即将到来的截止日期检索。 |
`fixtureBenefits` 作为示例数据导出，用于测试、演示和本地实验。它不是实时政府数据源或关于实际利益可用性的稳定性承诺。
### 评估和排名契约
`searchBenefits` 接受非识别性 `profile.persona` 和可选的每个维度 `weights`。内置角色预设为 `youth_jobseeker`、`university_student`、`newlywed_family`、`single_parent`、`senior` 和 `general`；请求权重仅覆盖提供的维度的预设。每个结果保持 `assessment` 与 `ranking` 分开：只有冲突的 `authoritative_structured` 约束可以产生 `conflict_detected`；派生文本和默认值永远不会硬阻塞。`ranking.score` 是相对相关性，而不是概率或资格，`ranking.breakdown` 解释其维度。角色、查询和权重仅影响排名。稳定的不透明 ID 绑定在一起，包括全零权重的情况。`getUpcomingDeadlines` 在结构化 UTC `applicationDeadline` 的基础上重用此契约。
### 嵌入核心包
```bash
pnpm add @mcp-gen-ui/core
```
```ts
import { BenefitToolService, FixtureBenefitRepository } from "@mcp-gen-ui/core";
const service = new BenefitToolService(new FixtureBenefitRepository());
const results = await service.searchBenefits({
query: "부산 취업 지원",
profile: { regionCode: "KR-26", employmentStatus: "unemployed" }
});
```
参见 [`docs/extending.md`](docs/extending.md) 获取自定义 `BenefitRepository` 实现、`SnapshotStore` 使用和扩展安全规则。
### 版本控制（pre-1.0）
该项目遵循 SemVer，但当包为 `0.x` 时，次要版本可能包括对公共 API 的破坏性更改。补丁版本应为向后兼容的错误修复。破坏性 0.x 次要版本将在更改日志和迁移说明中注明。
## 工具
stdio MCP 服务器当前暴露七种确定性工具：
| 工具 | 输入 | 输出 |
| --- | --- | --- |
| `searchBenefits` | `{ query, profile?, weights? }` | `benefit-search.v2`：源状态、评估、相对排名、来源、已验证链接和新鲜度。 |
| `listPersonas` | `{}` | 内置角色预设和主机选择的评分权重。 |
| `getBenefitDetail` | `{ id }` | 结构化的利益详情，包括已知 `applicationDeadline`。 |
| `getUpcomingDeadlines` | `{ profile?, withinDays?, weights? }` | `upcoming-deadlines.v2`；`withinDays` 是 1 到 365 的整数。 |
| `buildChecklist` | `{ benefitId }` | 文档检查清单，附不合资格警告。 |
| `getApplicationGuide` | `{ benefitId }` | 用户操作的应用步骤。 |
| `getChangeLog` | `{ entityId?, cursor?, limit? }` | 分页快照更改；`limit` 为 1-100（默认 50），每个条目标识其来源。 |
所有输入和成功输出都是严格的。未知键（包括类似 PII 的键）被拒绝。MCP 失败是稳定的 JSON 文本错误 (`mcp-error.v1`)；成功通过 `structuredContent` 和 `TextContent` 中的相同 JSON 暴露。
## 存储库模式
运行时数据选择是显式的：
| 变量 | 含义 |
| --- | --- |
| `MCP_GEN_UI_REPOSITORY_MODE` | `fixture`、`live` 或 `mixed`。`NODE_ENV=production` 时需要；非生产环境默认为 `fixture`。 |
| `MCP_GEN_UI_LIVE_SOURCES` | 可选的逗号分隔列表，来自 `youth-center,bokjiro,subsidy24`。省略会发现具有配置键的源。 |
| `YOUTH_CENTER_API_KEY` | 单独的온통청년密钥；无共享密钥回退。 |
| `BOKJIRO_API_KEY` / `SUBSIDY24_API_KEY` | 每个源的 data.go.kr 密钥。`DATA_GO_KR_API_KEY` 是它们的共享回退。 |
| `MCP_GEN_UI_CACHE_TTL_MS` | 实时/mixed 读取缓存，1 秒 - 24 小时；默认为 5 分钟。 |
| `YOUTH_CENTER_API_ENDPOINT` / `BOKJIRO_API_ENDPOINT` / `SUBSIDY24_API_ENDPOINT` | 可选的端点覆盖。每个必须保持其源的精确官方 HTTPS 源，不包含凭证、查询或片段。 |
| `MCP_GEN_UI_DB_PATH` | SQLite 快照/变更历史路径；默认为 `mcp-gen-ui-gateway.db`。使用 `:memory:` 进行短暂运行。 |
`live` 和 `mixed` 如果没有选择源或选定的源缺少其密钥，则会失败关闭。没有从实时数据到固定值的静默回退。每个响应都会携带 `dataStatus.mode`、`partial` 和每个源的观察结果。
参见 [`docs/data-sources.md`](docs/data-sources.md) 获取源契约和 [`docs/migration-v0.2-to-v0.3.md`](docs/migration-v0.2-to-v0.3.md) 获取 v2 迁移。
## 安全边界
- **无敏感标识符** 存储（居民编号、密码、证书、令牌）。
- 配置文件仅接受粗糙的枚举，如 ISO 地区代码和年龄段；未知或类似 PII 的字段会验证失败。
- 推荐是 **候选资格，而不是资格决定**，并附有警告。
- 只有单独结构化的权威约束才能报告冲突；提取的文本仍然是排名证据。
- **无登录、身份验证或提交自动化**。
## 文档
- [`docs/data-sources.md`](docs/data-sources.md) — 官方固定源归属、许可说明和源 URL 覆盖。
- [`docs/migration-v0.2-to-v0.3.md`](docs/migration-v0.2-to-v0.3.md) — 严格的 v2 契约和运行时迁移。
- [`docs/prd.md`](docs/prd.md) — 产品规格和范围。
- [`docs/host-prompts.md`](docs/host-prompts.md) — 推荐的主机提示 + 工具。
- [`docs/personas.md`](docs/personas.md) — 角色加权模型、预设理由和评分契约。
- [`docs/extending.md`](docs/extending.md) — 自带数据源和其他扩展点。
- [`docs/git-workflow.md`](docs/git-workflow.md) — 分支和 PR 工作流程。
- [`docs/roadmap.md`](docs/roadmap.md) — 里程碑状态和延迟工作（包括浏览器辅助）。
- [`CONTRIBUTING.md`](CONTRIBUTING.md)、[`SECURITY.md`](SECURITY.md)、[`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md)。
## 许可证
[Apache-2.0](LICENSE)。最初由 Team KOI 创建；在此重新实现和维护 — 参见 [`NOTICE`](NOTICE)。
