内容
# Hutch Core
最简单的可自行托管的MCP服务器，用于结构化代理数据。
Hutch Core 是无头、单用户且不附带电池的。指向一个MCP客户端（Claude Code、Cursor、Codex、VS Code），告诉你的代理“保存这个”，然后获取一个可查询的、支持可选模式的JSONB记录存储 — 没有仪表盘，没有登录屏幕，没有OAuth仪式。只有MCP端点和Postgres数据库。
这是开源引擎。具有网页仪表盘、发布视图、社交登录和组织共享的多用户产品是 [Hutch Cloud](https://app.hutchdb.com) — 请参见下面的[哪些功能迁移到了Hutch Cloud](#哪些功能迁移到了Hutch-Cloud)。
## 使用Docker快速开始
```bash
git clone https://github.com/ExpeditedProjects/hutch-core
cd hutch-core
# 可选：要求每次MCP调用都需要Bearer Token。
export HUTCH_API_KEY="$(openssl rand -hex 32)"
docker compose up
```
Core会迁移数据库并在端口3000启动。单用户 + 个人组织会在第一次身份验证的MCP或REST请求时插入 — 无需种子步骤。
## 不使用Docker快速开始
```bash
git clone https://github.com/ExpeditedProjects/hutch-core
cd hutch-core
npm install
cp .env.local.example .env.local
# 必需：HUTCH_DATABASE_URL
# 可选：HUTCH_API_KEY（如果未设置，所有请求都将被信任 — 适用于localhost，不适用于公共主机）
npm run db:migrate
npm run dev
```
MCP端点位于 `http://localhost:3111/api/mcp`（开发）或 `http://localhost:3000/api/mcp`（生产 / Docker）。
## 连接MCP客户端
如果设置了`HUTCH_API_KEY`，则每个MCP请求都必须包含 `Authorization: Bearer <key>` 头部。如果未设置，Core接受匿名请求（单用户本地模式）。
### Claude Code
```json
{
"mcpServers": {
"hutch": {
"type": "http",
"url": "http://localhost:3000/api/mcp",
"headers": {
"Authorization": "Bearer YOUR_HUTCH_API_KEY"
}
}
}
}
```
### Cursor / VS Code
两者都接受与上述相同的HTTP MCP服务器形状 — 将 `url` 设置为您的Core端点，并在 `headers.Authorization` 中传递Bearer Token。
### 测试端点
```bash
curl -X POST http://localhost:3000/api/mcp \
-H "Authorization: Bearer $HUTCH_API_KEY" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'
```
您应该看到 `hutch_*` 工具的列表（集合、记录、模式、视图）。
## 哪些功能迁移到了Hutch Cloud
Core故意保持小巧。如果您需要以下任何功能，请运行 [Hutch Cloud](https://app.hutchdb.com) 或自行fork Core并添加它们：
- 网页仪表盘（`/dashboard`，集合浏览器，记录网格，视图编辑器）
- 发布视图和公共只读页面（`/p/[slug]`，提交表单）
- OAuth 2.1授权服务器（`/api/oauth/*`，`/.well-known/oauth-*`）
- 社交登录（GitHub，Google），密码身份验证，会话Cookie
- 多用户组织，邀请，成员角色，共享
- 邀请的电子邮件投递
- 配额强制执行 / 计费钩子
> **claude.ai 网页需要OAuth。** 由于Core不附带OAuth授权服务器，因此将Core实例添加到claude.ai（网页应用）中不会开箱即用 — 该流程需要Hutch Cloud，或者您需要在Core前面添加自己的OAuth授权服务器。Claude Code、Cursor、Codex和VS Code都接受静态Bearer Token，工作正常。
## 架构
- **Next.js 16 应用路由器** — 一个静态登陆页面，一个MCP路由（`/api/mcp`），一个REST种子路由（`/api/v1/collections`）。其他所有内容都已删除。
- **Drizzle + Postgres** — 记录存储为JSONB，通过包含运算符和全文搜索进行查询。
- **MCP服务器** — 集合工具，记录工具（存储/查询/搜索/更新/删除/状态/转换），模式工具（描述/推断/更新），视图工具。
- **`src/lib/auth/seam.ts` 处的身份验证接口** — 如果设置了 `HUTCH_API_KEY`，则 `authenticate()` 需要匹配的 `Authorization: Bearer <key>`；否则，它会解析单用户上下文。接口是身份验证的唯一位置。
- **`src/lib/auth/singleton.ts` 处的单用户启动** — 一个用户，一个个人组织，在第一个请求时延迟插入。
## 烟雾测试
```bash
# 匿名模式（HUTCH_API_KEY 未设置）
SMOKE_BASE_URL=http://localhost:3000 npm run smoke
# 密钥模式
SMOKE_BASE_URL=http://localhost:3000 SMOKE_API_KEY=... npm run smoke
```
## 许可证
AGPL v3 — 请参见 [LICENSE](LICENSE)。贡献者签署CLA，以便维护者可以双重许可到Hutch Cloud — 请参见 [CONTRIBUTING.md](CONTRIBUTING.md) 和 [CLA.md](CLA.md)。
## 状态
Core稳定 enough，可用于单用户自行托管。重大更改发生在 `main` 分支；如果您需要稳定性，请固定提交。
