内容
# OKF 保险库
[](LICENSE)
[](package.json)
[](CONTRIBUTING.md)
一个可扩展的 [模型上下文协议（MCP）](https://modelcontextprotocol.io)
服务器和无头 CLI，用于 **开放知识格式（OKF）**。知识存储在 **PostgreSQL** 中，以实现快速的排名检索，但每次读取仍以 OKF Markdown 格式进行往返——因此，线路格式保持人类和代理友好，而存储则经过优化。
## 功能
- **REST API** — 捆绑包和概念的完整 CRUD，`/docs` 处的 OpenAPI 文档
- **MCP 服务器** — 代理优化工具，资源模板 (`okf://{bundle}/{path+}`)，提示，stdio 或可流式传输的 HTTP 传输
- **全文搜索** — Postgres `tsvector` + `pg_trgm`，具有容错模糊匹配
- **基于作用域的组织** — 全局、命名和项目作用域
- **实时目录合成** — 读取时合成 `index.md`（§6）和 `log.md`（§7）
- **图遍历** — `{concept}.links` 和 `{concept}.backlinks` 提取 OKF 参考
- **速率限制** — 滑动窗口（可配置的 RPS），每个 IP
- **关联 ID** — 跨所有请求的 `x-request-id` 跟踪
- **身份验证** — 通过 `API_KEY` 配置的 Bearer Token
- **CORS** — 可配置的源允许列表或 `*`
## 如何使用
### Docker Compose（推荐）
```bash
git clone https://github.com/alexandre-leites/okf-vault && cd okf-vault
cp .env.example .env
docker compose up -d # Postgres + vault server
# 服务器正在运行于 http://localhost:3000
```
### 仅使用 Dockerfile
```bash
docker build -t okf-vault server/
docker run -d \
-e DATABASE_URL=postgres://okfvault:okfvault@host:5432/okf_vault \
-p 3000:3000 \
okf-vault
```
### 手动构建
```bash
# 需求：Node.js >= 22.13，PostgreSQL >= 14
npm install
cp .env.example .env # 或 cp server/okfvault.example.yaml okfvault.yaml
npm run build
node dist/cli.js migrate # 应用数据库迁移
node dist/cli.js serve # REST API + MCP
```
## 如何使用 MCP 连接
服务器通过两种传输方式公开 MCP：
| 传输方式 | URL/机制 | 何时使用 |
| ------------------- | ------------------------ | ----------------------------- |
| **可流式传输的 HTTP** | `http://<host>:3000/mcp` | 远程客户端，共享设置 |
| **stdio** | 作为子进程启动 | 本地，无需网络 |
启动服务器：
```bash
okfvault serve --host 0.0.0.0 --port 3000 --migrate
# MCP 端点： http://<host>:3000/mcp
```
如果设置了 `API_KEY`，请在 HTTP 头中包含 `Authorization: Bearer <API_KEY>` 或在客户端环境中传递它。 将 `MCP_TRANSPORT` 设置为 `stdio` 或 `http` 以限制为单个传输（默认情况下为 `both`）。
有关连接细节，请参阅客户端自己的文档：
- [opencode MCP 文档](https://opencode.ai)
- [Claude MCP 文档](https://docs.anthropic.com/en/docs/build-with-claude/mcp)
- [Cursor MCP 文档](https://docs.cursor.com/context/model-context-protocol)
## MCP 工具
| 工具 | 描述 |
| -------------------------- | -------------------------------------------------------------------- |
| `okf_concept_search` | 搜索内存；返回轻量级预览（链接、标题、片段） |
| `okf_concept_get` | 通过 `link` 或 `bundle`+`path` 填充概念（跟踪读取次数） |
| `okf_concept_upsert` | 创建或更新概念（在更新时保存版本快照） |
| `okf_bundle_index` | 捆绑包目录列表（渐进式披露） |
| `okf_bundle_list` | 列出所有捆绑包 |
| `okf_bundle_create` | 创建捆绑包 |
| `okf_concept_links` | 概念正文中的 OKF 参考输出 |
| `okf_concept_backlinks` | 引用的给定概念的链接 |
| `okf_concept_history` | 列出概念的版本快照 |
| `okf_concept_read_version` | 读取特定的历史版本 |
| `okf_bundle_delete` | _破坏性 — 软删除捆绑包及其概念_ |
| `okf_concept_delete` | _破坏性 — 软删除概念_ |
捆绑包命名：使用保留的 **`global`** 捆绑包（始终存在，不区分大小写）用于跨项目知识（首选项、标准）；使用 git 仓库或项目名称用于项目特定知识。捆绑包 slug、概念路径和 `okf://` URI 不区分大小写并规范为小写。
### MCP 资源
| 模式 | 描述 |
| ------------------------ | ---------------------------- |
| `okf://{bundle}/{path+}` | 概念文档为 Markdown |
### MCP 提示
| 提示 | 描述 |
| ---------------- | ----------------------------------------- |
| `create_concept` | 使用正确的参数指导概念创建 |
## REST API
| 方法 | 路径 | 描述 |
| -------- | ------------------------------------------- | ------------------------------------ |
| `GET` | `/health` | 健康检查 |
| `POST` | `/okf/bundles` | 创建捆绑包 |
| `GET` | `/okf/bundles` | 列出捆绑包 |
| `DELETE` | `/okf/bundles/{bundle}` | 软删除捆绑包（级联） |
| `GET` | `/okf/bundles/{bundle}` | 目录列表（Markdown） |
| `GET` | `/okf/bundles/{bundle}/index.md` | 目录列表（§6） |
| `GET` | `/okf/bundles/{bundle}/log.md` | 更新历史（§7） |
| `GET` | `/okf/bundles/{bundle}/{concept}.md` | 读取概念 |
| `POST` | `/okf/bundles/{bundle}/{concept}.md` | 创建概念 |
| `PUT` | `/okf/bundles/{bundle}/{concept}.md` | 更新概念 |
| `DELETE` | `/okf/bundles/{bundle}/{concept}.md` | 软删除概念 |
| `GET` | `/okf/bundles/{bundle}/{concept}.links` | 概念链接 |
| `GET` | `/okf/bundles/{bundle}/{concept}.backlinks` | 链接到此概念 |
| `GET` | `/okf/search` | 排名全文 + 结构化搜索 |
交互式文档位于 `/docs`；OpenAPI 规范位于 `/openapi.json`。
## CLI
```bash
okfvault migrate # 应用迁移
okfvault bundle create acme-sales --title "Acme Sales"
okfvault bundle list
okfvault bundle index acme-sales --markdown # 渐进式披露
okfvault concept create acme-sales tables/orders --type "BigQuery Table" --title Orders
okfvault concept read acme-sales tables/orders
okfvault search --bundle acme-sales --type Playbook "revenue"
okfvault serve --migrate # 迁移然后服务
```
## 配置
解析优先级为 **CLI 标志 > `OKFVAULT_*` 环境变量 > 配置文件 > 默认值**。配置文件：`./okfvault.yaml`、`~/.config/okfvault/config.yaml` 或 `$OKFVAULT_CONFIG`（YAML，支持注释）。
所有配置键都需要 `OKFVAULT_*` 前缀，以避免与 CI/Docker/编排环境变量冲突。
| 配置键 | 环境变量 | CLI 参数 | 类型/示例 | 默认值 |
| ------------------------ | --------------------------------- | ------------------------- | ----------------------------------------- | ------------------------------------------------------- |
| `DATABASE_URL` | `OKFVAULT_DATABASE_URL` | `--database-url` | `postgres://user:pass@host:5432/db` | `postgres://okfvault:okfvault@localhost:5432/okf_vault` |
| `DATABASE_TEST_URL` | `OKFVAULT_DATABASE_TEST_URL` | （仅测试） | `postgres://user:pass@host:5432/okf_test` | （空 — 集成测试跳过） |
| `HOST` | `OKFVAULT_HOST` | `--host` | `0.0.0.0` | `0.0.0.0` |
| `PORT` | `OKFVAULT_PORT` | `--port` | `3000` | `3000` |
| `LOG_LEVEL` | `OKFVAULT_LOG_LEVEL` | `--log-level` | `info`，`debug`，`warn`，`error`，`trace` | `info` |
| `LOG_PRETTY` | `OKFVAULT_LOG_PRETTY` | `--log-pretty` | `true`，`false`，`1`，`0` | `false` |
| `CORS_ORIGINS` | `OKFVAULT_CORS_ORIGINS` | `--cors-origins` | `*` 或 `http://a.com,http://b.com` | （空 — 禁用） |
| `API_KEY` | `OKFVAULT_API_KEY` | `--api-key` | `my-secret-token` | （空 — 身份验证禁用） |
| `MAX_BODY_SIZE` | `OKFVAULT_MAX_BODY_SIZE` | `--max-body-size` | `1048576` | `1048576` |
| `RATE_LIMIT_RPS` | `OKFVAULT_RATE_LIMIT_RPS` | `--rate-limit-rps` | `100` | `100` |
| `MCP_TRANSPORT` | `OKFVAULT_MCP_TRANSPORT` | `--mcp-transport` | `both`，`stdio`，`http`，`sse` | `both` |
| `BUNDLE_STORAGE_ENABLED` | `OKFVAULT_BUNDLE_STORAGE_ENABLED` | `--enable-bundle-storage` | `true`，`false` | `false` |
| `BUNDLE_STORAGE_PATH` | `OKFVAULT_BUNDLE_STORAGE_PATH` | `--bundle-storage-path` | `/data/okf-vault` | （空 — 禁用） |
## 开发
```bash
# 所有命令都在项目根目录运行；npm 委托给 server/
npm run dev # 具有热重载的 CLI（tsx 监视）
npm run typecheck # 使用 tsc 进行类型检查
npm run lint # 使用 ESLint 进行 linting
npm run db:generate # 从架构更改中生成新的迁移
npm test # Vitest（集成测试在没有
# OKFVAULT_DATABASE_TEST_URL 的情况下跳过）
# 您也可以直接在 server/ 中运行命令
cd server && npm test
```
## 架构
请参阅 [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) 以获取完整的架构分解。
服务器源代码位于 [`server/`](server/) 中。
## 社区
- [行为准则](CODE_OF_CONDUCT.md)
- [贡献指南](CONTRIBUTING.md)
- [变更日志](CHANGELOG.md)
- [安全策略](SECURITY.md)
## 许可证
[Apache License 2.0](LICENSE) 附带 [NOTICE](NOTICE).
---
### 非隶属声明
该项目是 [开放知识格式（OKF）规范](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md) 的独立实现，与 Google LLC 无关、未获得 Google LLC 赞助或认可。本仓库中的所有代码均从头开始独立编写。
