setoku

<p align="center"> <img src="./site/assets/favicon.svg" alt="Setoku" width="72" height="72"> </p> # Setoku **让任何 AI 都能流畅地理解您公司的数据。** Setoku 是一个小型、自我托管的 MCP 知识服务器，搭配 Claude Code 技能，用于连接您的数据。它做两件事：为您的 AI 提供只读方式查询您的数据，并记住这些数据的含义（指标定义、注意事项），随着使用次数的增加而变得更好。您可以要求一个仪表板，并将其发布到一个链接，整个团队都可以查看实时数据。MCP 服务器适用于您已经拥有的任何 AI，并且没有模型在服务器上运行，因此没有额外的推理成本。 - **问题。** 您公司对自己的了解都存在于人们的脑海中：哪个指标是真正的指标，为什么“付费客户”比看起来更复杂，什么样的查询会出错，日志中显示了什么。当这些信息没有被 Agents 获取时，他们会猜测并自信地给出错误答案。 - **它做什么。** Setoku 是您数据和运营的共享、策划的记忆库。它存储这些定义和注意事项，并在您的 AI 回答之前将其提供给 AI，这样 AI 就可以按照您公司实际的方式计算事物，并且随着使用次数的增加而变得更好。 - **安全地指向您的数据。** 代理仅运行只读、审计过的查询，不能更改 Setoku 所知道的内容；人类在代理的循环之外批准这一点。 - **它很便宜。** Setoku 本身不运行任何 AI；推理发生在您已经付费的 AI 中。整个部署是一个小型 VPS。 一个大脑，两种问题：_“上季度收入是多少？”_ 和 _“自部署以来有哪些错误？”_ 业务指标和运营真相，两种问题都以只读方式得到回答。 今天，大脑主要存储 **数据和运营** （您的表格、指标和日志的含义）。同样的想法可以适用于更多内容（个人上下文、房屋设计约定）；请参见 [docs/memory.md](./docs/memory.md)。 _Setoku = **set** （数学）× **oku** （奥， innermost）：您 AI 下面的最底层。_ --- ## 实时试用 有一个公共演示连接到一个合成数据集，用于一个虚构的职业体育俱乐部， **Bonita Bulldogs**，涵盖售票、粉丝/CRM、赞助、商品、场馆、人员配备、工资、营销、比赛事件和广播媒体权利。 1. 在 **Claude.ai** （或任何 MCP 客户端）中，打开 **设置 → 连接器 → 添加自定义连接器**，并粘贴以下内容作为服务器 URL。令牌位于 URL 中，因此无需输入单独的密钥。 ``` https://demo.setoku.com/mcp/fdb6bb54d746ba8e00d698ff2183228b682b8272bfef78e0 ``` 2. 用普通语言提问。Setoku 首先向您的 AI 提供策划的定义（免费试用，`scanned` = 已参加，货币单位为美分），因此它按照业务实际计算数字，而不是从列名中猜测。试试： - _“我们有多少独特粉丝？”_ → **71,204**，按规范电子邮件地址去重，排除内部/测试帐户，而不是原始 92,118 名。 - _“这个赛季我们的门票收入是多少？”_ → **$46.8M**，美分兑换成美元，退款/交换/补偿排除在外。 - _“我们的季票续签率是多少？”_ → 跨越三个赛季的售票历史。 - _“我们的总年度收入是多少，媒体权利是多少？”_ → **~$192M**，跨越五个系统，换算成相同的单位；媒体权利是最大的项目，~$90M。 - _“我们的商品总收入是多少？”_ → 它 **标记** 大部分商品通过 Fanatics 销售，而不是在此数据中，而是返回一个错误的总数。 3. 尝试一个应用程序。要求 Claude 创建一个基于相同数据的仪表板，然后发布到一个链接。两个实时示例，目前正在演示数据上运行： - [赞助定价表](https://demo.setoku.com/admin/p/7e38381ced6517329947b14d)：库存和赞助位置的费率。 - [粉丝生命周期价值](https://demo.setoku.com/admin/p/b059da830dcb3e70437d5dea)：按门票、商品和场馆消费对粉丝进行分段。 完整的演练， `/admin` 审批界面和数据模型： [`demo/README.md`](./demo/README.md)。 --- ## 它是如何工作的 Setoku 为 AI 提供三种 MCP 工具和一个规则：在触摸数据之前查找数据的含义。 1. **上下文工具** （`find_context`、`get_metric`、`report_correction`）首先读取数据的含义：规范的指标定义、实体文档和使查询出错的注意事项（例如“活跃用户”排除内部测试帐户；退款必须从收入中减去；状态列仅为当前状态，因此您从日志表中计算事件）。AI 可以提出对 Setoku 已知内容的更改，但管理员在审批页面上批准，超出代理循环，因此注入的会话无法重写大脑。 2. **只读查询** （`get_schema`、`run_query`）在行上限、语句超时、表允许列表和追加审计日志的限制下运行。只读权限由数据库引擎强制执行（仅限 SELECT 角色），而非在代码中解析 SQL。 3. **应用程序工具** （`publish_app`、`update_app`）将答案转换为一个小型 Web 应用程序，基于实时数据发布到一个链接，任何团队成员都可以打开。无需 SQL。 代理首先查找上下文，然后运行查询，因此它按照业务实际计算事物，而不是从列名中猜测。一旦设置完成，**任何 MCP 客户端** 都可以使用它：Claude、Codex 或您运行的任何 AI。 它提供 **工具，而不是模型**。服务器上没有 AI 运行；推理发生在您已经使用的 AI 中。这意味着没有 AI API 密钥和每个查询的 AI 成本：整个部署是一个小型 VPS 加上您的团队已经拥有的 AI 席位。 ## 应用程序：构建在数据上，共享链接 一旦您的 AI 可以读取并 **理解** 数据，自然而然的下一步是在其基础上构建一些东西。要求您的代理创建一个图表、投票或分类列表 - 它编写一个自包含的 **应用程序** （`publish_app`）并为您提供一个 URL。无需部署，无需维护前端；非技术团队成员只需描述他们想要的内容并进行编辑即可（“使条形图变为绿色，添加上一季度”）。 - **基于实时数据，只读。** 应用程序通过与所有其他内容相同的受控路径查询 - 行上限、审计、仅限 SELECT 的数据库角色。应用程序永远不会获得对其源数据的写入权限。 - **它们自己的私有状态。** 每个应用程序都保留其自己的状态 - 待办事项、投票计数、笔记、注释 - 在一个属于 _应用程序_ 的沙盒中，而不是您的数据库。因此，应用程序可以真正交互（如果注入的应用程序仍然无法触及您的数据；最坏的情况是它会弄乱自己的笔记）。有用的技巧：使用 ID 标记业务行以将其标记为“已审查”或附加注释，在只读数据的顶部叠加，而无需写入源数据。 - **可通过链接共享。** 团队链接是登录门控的；管理员可以翻转一个公共凭证免费 URL。页面在沙盒中运行，无网络连接，因此已发布的应用程序无法联系家里。 ## 我们为什么要开发它 **我们很好奇。** 有很多 AI 内存存储和数据网关。将两者结合起来，并促使代理在收集有关数据知识的过程中，似乎有用且有趣。 **我们很节俭。** 我们想要一些东西，它可以在一个小型盒子上运行，在 Pro/Max 订阅或廉价模型上运行，无需额外的推理成本，基本上可以自行设置（无需支付现场工程师），可以在提供商之间移植，并且是开源的。 **我们很谨慎。** HR 平台、CRM 和云都宣布了“上下文层”。他们希望您的业务含义在他们的服务器上积累，这样它就永远不会离开。上下文比数据更深入，托管的上下文层没有导出按钮。Setoku 存在于此，以便理解在您拥有的盒子上积累，而不是在托管层上。 **我们和一些朋友想要同样的东西。** - **[Hedgy](https://www.hedgy.works)**：保持扩展而无需雇佣。 从实时日志和数据中调试，找到增长杠杆，并通过更多数据更好地匹配候选人和公司。 - **[Baggu](https://baggu.com)**：为员工提供最先进的工具。 更快的入职培训，以及一种安全的方式来针对真实数据进行编码。 - **[Tlon](https://tlon.io)**：尝试为代理提供策划的数据。 - **体育分析师**：跨不同数据查询。 - **学术实验室**：思考假设与真实论文、数据和草稿。 这是一件小事，但对我们来说很有用。 也许对你也很有用。 ## 如何部署它 Setoku 作为 Claude Code 插件安装，因此设置在 Claude 中运行。添加插件（此时无需服务器），然后从您的主项目目录运行 onboarding，您的代码库是 Setoku 要学习的内容： /plugin marketplace add Hedgy-Labs/setoku /plugin install setoku@setoku /setoku:onboard `/setoku:onboard` 在存储库中为 Setoku 设置服务器（配置并启动一个小型 VPS，或连接到您已经拥有的一个），将此 Claude 连接到它，将您的数据库连接到只读状态，并从您的代码中生成第一个知识。您需要一个 VPS 来使用（类似于 OVH 的 [VPS-2](https://us.ovhcloud.com/vps/)，约 12 美元/月），以及数据库的管理连接 URL。您在与数据相关的任何内容上保持循环。（或者只需告诉 Claude “设置 Setoku。”） 插件随附整个工作流程作为技能： /setoku:onboard 在存储库中首次设置 Setoku。 /setoku:connect 添加数据源或自定义集成。 /setoku:generate 从您的代码编写业务上下文。 /setoku:curate 审查和批准待处理知识。 <details> <summary>或手动启动服务器</summary> 在新的 Ubuntu VPS 上执行一个命令（~$12/月）： ```bash git clone https://github.com/Hedgy-Labs/setoku /opt/setoku && cd /opt/setoku SETOKU_ADMIN_USER=you ./deploy/bootstrap.sh ``` 它安装 Docker，生成密钥，获取真正的 HTTPS 证书（如果您还没有域名，则使用 `<your-ip>.sslip.io`），并将整个堆栈启动。它打印连接您的 AI 和日志排水令牌的命令。（`SETOKU_ADMIN_USER` 是它创建的 `/admin` 登录名；设置它以便脚本无人值守运行，或者省略它并交互式地询问一次。） 然后添加插件并运行 `/setoku:onboard` 从您的项目；它检测您刚刚创建的盒子，连接您的数据库（凭证保留在您的 env 中；只有 env-var _name_ 进入配置），并从您的代码中生成第一个知识。 </details> 重点在于代理可以查询您的 Postgres；如果您是工程师，它已经可以做到。重点在于 **含义被捕获一次并** **与整个团队共享**：`add-teammate` 为任何人创建连接器，因此非技术团队成员可以用普通语言查询和可视化他们自己的数据（“显示我按周的注册人数”）并获得 **正确** 的数字，因为您的注释随行。 ## 连接器 指向您已经拥有的数据。每个源都进入一个本地 [ClickHouse](https://clickhouse.com/) 数据湖，有意为此：代理编写任意查询（扫描、GROUP BY、整个表格聚合），而列式引擎在大约一秒内回答这些查询，因此应用程序和仪表板保持快速。 - **您的应用程序数据库（PostgreSQL）**：连接只读，然后镜像到盒子的分析引擎，按 cron 计划。仪表板和大量问题在镜像上运行（快速，无生产负载）；实时连接用于验证和镜像不包含的内容。 - **摄入到湖中（ClickHouse）**：GitHub（问题、PR 和提交）、Vercel 和 Render（部署和日志）、Slack（消息）、Mercury（银行和财务）。 没有您的源的连接器？包含的设置技能为您提供模式，让您的编码代理可以自己连接。您维护几个经过验证的模式，而不是每个供应商一个连接器。请参见 [CONTRIBUTING.md](./CONTRIBUTING.md)，或打开一个问题。 ## 高级架构 所有内容都是一个 `docker compose` 在一个 VPS 上运行。只有 Web 代理面向互联网；数据库从未暴露。 ```mermaid flowchart LR A["您 + 您的 AI"] subgraph box["您的 VPS · docker compose（仅代理公开）"] GW["网关（MCP）<br/>上下文 + 只读查询工具"] K[("知识库<br/>数据含义")] LAKE[("湖（可选）<br/>日志 · 事件 · 应用程序数据库镜像")] ADMIN["审批页面<br/>人类接受知识更改"] end DATA[("您的数据<br/>Postgres · SaaS API · 日志")] A -- "MCP" --> GW GW --> K GW -- "只读，实时" --> DATA GW --> LAKE A -. "提出知识" .-> ADMIN ADMIN --> K ``` **两部分：** 1. **配置器** 按需将每个数据源连接起来：实时查询 Postgres（只读），摄入日志和事件，从 API 拉取数据，归档 Slack。您维护几个经过验证的模式，而不是每个供应商一个连接器。 2. **网关** 为代理提供两种 MCP 工具： _上下文_ 工具（查找数据的含义）和 _数据_ 工具（`get_schema`、`run_query`；只读、审计、路由到数据存储的位置）。 **膜：使它安全注入。** 代理只能 _提出_ 知识；人类在审批页面上接受它，超出代理循环。因此，被恶意日志行骗取的代理可以提出无意义的内容，但如果没有人类点击，则不会产生任何影响。 **框中运行的内容：** | 组件 | 角色 | | ------------------------------------ | ---------------------------------------------------------------------------------- | | **Caddy** | HTTPS 边缘，唯一公开的容器 | | **网关** | MCP 服务器（上下文 + 查询工具）和 `/admin` 审批界面 | | **Postgres** | 知识库和管理员帐户 | | **ClickHouse + Vector** _(可选)_ | 日志/事件/遥测的湖泊，以及应用程序数据库的分析镜像（仪表板的读取路径） | Setoku 使用 SELECT-ONLY 角色读取您的数据库；只读权限由数据库引擎强制执行，而非在代码中解析 SQL。如果启用了湖泊，它还会在您的盒子上保留允许列表表格的分析副本，按 cron 刷新。该镜像使仪表板快速（列扫描而不是锤击生产），并且是可处置的：从源重新构建，每个通过，排除备份，一旦表格离开允许列表。它永远不会离开盒子。 ## 安装帮助 它是开源的，因此您可以今天自行托管。如果您不想，我们很乐意帮助设置：我们将其连接到您的数据，在您身边捕获第一个知识，并将其移交给您。邮箱 [hello@setoku.com](mailto:hello@setoku.com)。 --- Apache-2.0 ([LICENSE](./LICENSE)). Contributing: [CONTRIBUTING.md](./CONTRIBUTING.md) (DCO 签署). 安全 & 令牌姿势: [SECURITY.md](./SECURITY.md). 设计 & 路线图: [SPEC.md](./SPEC.md). 代码保留的安全不变式（I1–I9）: [docs/invariants.md](./docs/invariants.md). 结构化事实模型 + 紧凑/自动判断设计 (#10): [docs/knowledge-facts.md](./docs/knowledge-facts.md).