AWS DevOps Study KB

一个自托管的备忘知识库，用于 AWS DevOps Engineer Professional 考试备考 —— 笔记不是由你 写的，而是由你的 AI 代理写的。 向 Claude、OpenWebUI 或任何其他代理提问一个学习问题 （"gp3 和 io2 之间的基线性能差异是什么，我分别在什么情况下选择它们？"）， 它会在回答的同时，把一份结构良好、带标签的备忘保存到这里 —— 如果它还连接了 AWS Knowledge MCP server，内容会以官方 AWS 文档为依据。 下周再问同样的问题时，代理会直接找到这份备忘，而不是重新推导答案。

没有文件夹，无需手动整理 —— 每份备忘都是扁平的、带标签的、可全文搜索的。Web UI 在设计上只读：所有写入都由代理负责。

you: "explain EBS volume types, baseline performance, and when to pick each"
agent: [searches this KB — nothing found] [answers, grounded in AWS docs] [saves a memo,
        tagged ebs, storage, exam:resilient-cloud-solutions]

 ...two weeks later...

you: "remind me about EBS gp3 vs io2"
agent: [searches this KB — finds the memo] "Yep, saved this one already — gp3 baseline is
        3,000 IOPS / 125 MiB/s regardless of size..."

工作原理

一个 Node.js/TypeScript 服务以三种方式暴露同一个备忘存储，因此无论你的 AI 客户端 支持什么协议都能使用：

• MCP（/mcp，streamable-HTTP）—— 适用于 Claude Code、Claude Desktop、OpenWebUI 或任何其他 原生支持 MCP 的客户端。工具：create_memo、search_memos、get_memo、list_tags、update_memo、 delete_memo。

• REST + OpenAPI（/api/v1/*，规范位于 /openapi.json）—— 适用于只支持 OpenAPI/REST 工具调用的代理框架和机器人（自定义 GPT Actions、LibreChat、自建的 Telegram 机器人等）。

• Web UI（/）—— 为你提供的只读浏览/搜索/标签筛选视图，通过简单的 cookie-session 登录进行门控。完全没有创建/编辑表单 —— 这不是疏忽，而是有意为之。

这三种方式都是基于同一个 SQLite 后端服务的薄适配层（搜索为 FTS5 全文 + 标签 筛选），因此 MCP 客户端看到的内容与 REST 客户端看到的内容不会出现偏差 —— 更多 架构细节见 CLAUDE.md。

Related MCP server: OmniHub

快速开始

git clone <this-repo-url>
cd aws-devops-study-kb
cp .env.example .env        # fill in API_BEARER_TOKEN and SESSION_COOKIE_SECRET (see below)
npm install
npm run dev                 # http://localhost:8000

生成真实的密钥，而不是保留 .env.example 中的占位符：

openssl rand -hex 32   # → API_BEARER_TOKEN
openssl rand -hex 32   # → SESSION_COOKIE_SECRET

如需持久化、可通过互联网访问的部署（以便云端托管的代理或 Telegram 机器人也能 访问），请参阅 docs/deployment.md —— Docker Compose + Cloudflare Tunnel，无需开放任何入站端口。

连接 AI 代理

每个使用者都需要来自 .env 的 bearer token（API_BEARER_TOKEN），格式为 Authorization: Bearer <token>。根据你的客户端选择对应的接入方式。

MCP 客户端（Claude Code、Claude Desktop、OpenWebUI、……）

Claude Code，连接到一个正在运行的部署：

claude mcp add --transport http aws-devops-study-kb https://<your-host>/mcp \
  --header "Authorization: Bearer <API_BEARER_TOKEN>"

Claude Desktop 或任何通过 mcpServers JSON 块配置的客户端：

{
  "mcpServers": {
    "aws-devops-study-kb": {
      "type": "http",
      "url": "https://<your-host>/mcp",
      "headers": { "Authorization": "Bearer <API_BEARER_TOKEN>" }
    }
  }
}

OpenWebUI：如果你的 OpenWebUI 版本原生支持 MCP，可以将其添加为 MCP 工具服务器 （Settings → Tools），使用相同的 URL 和 header。

连接后，服务器的 MCP instructions 字段（遵循该字段的客户端会自动读取）已经会引导模型 在回答前先搜索，并主动保存备忘 —— 如果你想通过系统提示词让这一行为变得 明确且可靠，而不是依赖客户端自行读取，请参阅 docs/agent-persona.md。

OpenAPI/REST 工具调用客户端

适用于任何导入 OpenAPI 规范而非使用 MCP 协议的客户端（自定义 GPT Actions、LibreChat、 自定义机器人）：

• 规范 URL：https://<your-host>/openapi.json（受 bearer-token 保护 —— 获取时需携带该 header）

• 如果你的客户端需要文件而不是实时获取，仓库中还提交了一份静态副本，位于 openapi/generated.json（每次 schema 变更后用 npm run generate:openapi 重新生成）。

• 每次调用都需要相同的 Authorization: Bearer <API_BEARER_TOKEN> header。

标签约定

没有文件夹 —— 标签是唯一的组织结构，因此代理需要一致地使用它们。 exam:<domain> 用于 AWS DevOps Pro 考试的 6 个领域，外加自由形式的主题标签 （ebs、s3、codepipeline、……）。完整约定及其面向代理的强制执行/文档位置， 见 docs/tag-conventions.md。

开发

npm test              # vitest — memoService, REST API, and MCP tool round-trips
npm run typecheck      # tsc --noEmit
npm run build           # compiles to dist/ (used by the Docker image)

如果你要扩展此项目，请参阅 CLAUDE.md 中的完整架构说明（为什么选择 SQLite+FTS5、为什么使用单一共享服务层、认证模型、已知陷阱）。

许可证

MIT