内容
<p align="center">
<img src="public/s33k-logo.png" alt="s33k" width="160" />
</p>
# s33k
s33k（读音为“seek”）是一个开放、自托管的工具，适用于单个人监控自己的网站，完全由您自己的LLM通过模型上下文协议（MCP）驱动。它将您关注网站的三个方面结合在一个您可以从Claude、Cursor或任何MCP客户端控制的地方：
- **搜索引擎优化（SEO）.** 跟踪您关注的关键词在Google上的排名。
- **AI搜索推荐（AEO）。** 哪些AI引擎（如ChatGPT、Claude、Perplexity、Gemini、Copilot）实际上向您的网站发送访客，通过真实的推荐流量进行衡量。
- **分析.** 页面流量、来源、参与度、滚动深度、点击和表单提交，由s33k自己的无cookie beacon收集。
您可以通过询问LLM来运行所有这些功能。无需学习SEO、AEO和分析功能的操作界面：您将s33k连接到MCP服务器，然后询问问题，如“我的网站表现如何？”或“哪些页面被AI搜索定位？”您的LLM将调用正确的工具。所有操作都在您托管的堆栈上运行，因此您的数据保留在您自己的机器或服务器上。
s33k是一个单用户、自托管项目。它适用于跟踪自己的网站（或少数网站）。无需注册、无需计费、无需多租户账户：您在配置文件中设置一个管理员登录名，就这样。
## 致谢
s33k是[`towfiqi/serpbear`](https://github.com/towfiqi/serpbear)（MIT）的分支。它保留了SerpBear的Google排名跟踪核心，并添加了无cookie分析beacon、AI推荐（AEO）层、每个页面流量与排名绑定的计分板，以及MCP控制平面。实时Google排名来自[Serper](https://serper.dev)，一个SERP API，您可以自带密钥。参见[许可证](#许可证)。
## 三大支柱
1. **SEO.** 跟踪每个网站的关键词，每个关键词映射到其目标页面，并抓取实时Google排名。Serper是排名数据源：您在[serper.dev](https://serper.dev)获取自己的密钥，粘贴进去，结果约两分钟后到达。
2. **AI搜索推荐（AEO）。** s33k通过分类推荐流量来检测哪些AI引擎向您发送访客。您可以看到每个引擎的访客和推荐流量中的AI份额。无需查询LLM来执行此操作：它只读取真实的第一方推荐数据。
3. **分析.** s33k自带无cookie、无个人识别信息（PII）自动捕获脚本。您在网站上粘贴一个标签，它记录页面浏览量、首次触达来源、点击、表单提交、滚动深度和参与时间，无需逐个元素设置。所有数据都存储在s33k自己的数据库中。
该产品是连接所有三个方面的MCP控制平面。每个页面的计分板将每个页面的流量与其实时Google排名绑定，并标记内容空白（有流量但无跟踪关键词的页面）和无效关键词（无流量但有目标页面）。
## 您可以询问的内容
所有操作都通过MCP由您的LLM驱动。以下是工具可以回答的高级问题的几个示例：
- **跨支柱简报.** “给我example.com的s33k简报。” 每日站会：标题、每个支柱的部分和最重要的事情。
- **开始使用.** “我刚刚连接了s33k，我应该从哪里开始？” 有指导的入口，根据您的设置状态读取并指定下一个最重要的步骤。
- **每个页面的计分板.** “显示example.com的每个页面的计分板。” 每个页面的流量与其跟踪的关键词和实时排名绑定。
- **AI着陆页面.** “对于example.com，哪些页面是AI搜索的着陆页面？” 每个着陆页面的首次触达来源，包括AI引擎。
- **排名快速提升.** “什么是我的突破口关键词？” 排名刚好在第一页之外的关键词，通常只需小小的推动就能成功。
- **转化目标.** “创建一个名为Demo Booked的目标，当有人到达/demo/thanks时，”然后“我的Demo Booked转化率从有机搜索是多少？”
- **命名转化目标、UTM活动和保存的细分,** 所有这些都通过MCP。
## MCP工具
s33k公开了72种MCP工具和5种只读知识资源，所有这些都共享一个权威注册表，位于`mcp/src/tools.ts`。主要组：
- **跨支柱（从这里开始）：** `start_here`、`briefing`、`insights`、`alerts`、`executive_summary`、`weekly_digest`、`page_scoreboard`、`entry_pages`、`entry_page_report`、`content_performance_report`、`conversion_attribution`、`portfolio_summary`。
- **SEO：** `list_keywords`、`add_keyword`、`update_keyword`、`delete_keyword`、`refresh_keywords`、`striking_distance`、`seo_report`、`site_audit`、`cannibalization_detection`、`content_gap`、`competitor_visibility`、`discover_pages`、`get_insight`（Google Search Console）。
- **AI搜索推荐（AEO）：** `ai_referrals`、`ai_visibility`、`aeo_report`。
- **分析：** `traffic_summary`、`human_traffic`、`human_analytics`、`channel_report`、`campaign_report`、`live_view`、`funnel_analysis`、`period_compare`、`traffic_breakdown`、`traffic_timeseries`、`top_events`、`engagement`，以及自动捕获读取`top_clicks`、`form_submissions`、`scroll_depth`、`page_engagement`、`web_vitals`、`conversions_by_source`。
- **转化目标和细分：** `create_goal`、`list_goals`、`delete_goal`、`goal_analytics`、`suggest_goals`、`segment_save`、`segment_list`、`segment_delete`、`segment_analytics`。
- **域名和上线：** `list_domains`、`create_domain`、`onboard`、`setup_status`、`install_instructions`。
- **信任和自我支持：** `security_facts`、`export_data`、`help`。
五个知识资源（`knowledge://capabilities`、`knowledge://setup`、`knowledge://reasoning`、`knowledge://troubleshooting`、`knowledge://trust`）公开了与`help`工具相同的产品知识层，因此客户端可以将整个文档拉入上下文。完整的工具描述位于[`mcp/README.md`](mcp/README.md)和`utils/knowledge.ts`。
## 安装
两种运行s33k的方式。Docker是最快且推荐的方式。无论您如何启动应用程序、数据库和MCP服务器，都在您控制的基础设施上。分析由s33k自己的beacon收集，因此无需安装其他内容。
### 选项A. Docker（推荐）
您需要Docker和Docker Compose。从终端：
```bash
git clone https://github.com/benjaminard/s33k.git
cd s33k
./scripts/setup-env.sh # 写入.env文件，包含强随机密钥，打印管理员登录名和API密钥
docker compose up -d --build
```
打开http://localhost:3000并使用脚本打印的凭证登录。安装完成：应用程序和Postgres数据库一起启动，架构在启动时迁移，beacon准备好粘贴到您的网站上。保存脚本打印的API密钥，您将使用它在下面连接LLM。
如果您更喜欢自己设置密钥？运行`cp .env.example .env`，填写它（`.env.example`文档每个变量），然后`docker compose up -d --build`。
**一键云部署.** 在主机上运行s33k，而不是在笔记本电脑上：
[](https://render.com/deploy?repo=https://github.com/benjaminard/s33k)
Render读取此存储库中的[`render.yaml`](render.yaml)并配置应用程序和托管的Postgres，生成`APIKEY`和`SECRET`并提示输入密码。 Railway一键式模板可以使用相同的环境配方从您自己的Railway仪表板发布；参见[`DEPLOY.md`](DEPLOY.md)。
### 选项B. 从源代码运行（Node 20）
```bash
git clone https://github.com/benjaminard/s33k.git
cd s33k
nvm use 20 # 仓库通过.nvmrc锁定Node 20（或：nvm install 20 && nvm use 20）
npm ci
cp .env.example .env # 然后编辑它（参见下文）
npm run dev
```
在启动前编辑`.env`：设置`USER_NAME`和`PASSWORD`（您的单个管理员登录名），使用`openssl rand -hex 34`生成`SECRET`，使用`openssl rand -hex 24`生成`APIKEY`，并从[serper.dev](https://serper.dev)添加您自己的`SERPER_API_KEY`（或在设置后在Web UI中粘贴）。如果`DATABASE_URL`未设置，则使用本地SQLite文件。s33k然后在http://localhost:3000运行，并在首次启动时创建其架构。`.env.example`文档中的每个变量。
## 添加您的域名并粘贴beacon
一旦MCP服务器连接，您就可以通过LLM在一个步骤中上线您的网站（“从头开始上线example.com”），或者在Web UI中添加域名。无论哪种方式，s33k都会给您一个跟踪代码段。在您的网站上粘贴这个单一的`s33k.js` beacon标签（在`<head>`中，或通过您的标签管理器），流量、来源、点击、表单提交、滚动深度和参与度就会开始流入。代码段是无cookie的，不会捕获任何PII。
## 通过MCP连接您的LLM
这是您实际使用s33k的方式：将它作为MCP服务器连接到您的AI客户端，然后提问。对于本地（stdio）路径，请在构建MCP服务器后：
```bash
cd mcp && npm ci && npm run build && cd ..
```
s33k通过两种方式支持MCP，您可以根据客户端选择：
- **本地（stdio）。** 当s33k在与客户端相同的机器上运行时最简单。运行`node mcp/dist/index.js`，读取您的密钥作为`S33K_API_KEY`，将应用程序URL作为`S33K_BASE_URL`。
- **远程（HTTP + Bearer）。** 当s33k在服务器上运行时。让客户端指向`<BASE_URL>/api/mcp`，并带有`Authorization: Bearer <APIKEY>`头部。
`<APIKEY>`是来自您的`.env`文件（设置脚本打印的相同值）。
### Claude 代码
本地（stdio）：
```bash
claude mcp add s33k \
-e S33K_API_KEY="$(grep '^APIKEY=' .env | cut -d= -f2)" \
-e S33K_BASE_URL=http://localhost:3000 \
-- node "$(pwd)/mcp/dist/index.js"
```
远程（HTTP + Bearer），当s33k在服务器上运行时：
```bash
claude mcp add --transport http s33k https://YOUR_S33K_URL/api/mcp \
--header "Authorization: Bearer YOUR_APIKEY"
```
重启客户端，然后尝试：“给我example.com的s33k简报。”用`claude mcp list`确认。
### 游标
添加到`.cursor/mcp.json`（项目）或`~/.cursor/mcp.json`（全局）。本地stdio：
```json
{
"mcpServers": {
"s33k": {
"command": "node",
"args": ["/绝对路径/到/s33k/mcp/dist/index.js"],
"env": { "S33K_API_KEY": "YOUR_APIKEY", "S33K_BASE_URL": "http://localhost:3000" }
}
}
}
```
或远程HTTP（将密钥保留在文件之外，通过环境变量）：
```json
{
"mcpServers": {
"s33k": {
"url": "https://YOUR_S33K_URL/api/mcp",
"headers": { "Authorization": "Bearer ${env:S33K_APIKEY}" }
}
}
}
```
### Codex CLI
添加到`~/.codex/config.toml`。本地stdio：
```toml
[mcp_servers.s33k]
command = "node"
args = ["/绝对路径/到/s33k/mcp/dist/index.js"]
[mcp_servers.s33k.env]
S33K_API_KEY = "YOUR_APIKEY"
S33K_BASE_URL = "http://localhost:3000"
```
或远程HTTP：
```toml
[mcp_servers.s33k]
url = "https://YOUR_S33K_URL/api/mcp"
bearer_token_env_var = "S33K_APIKEY"
```
然后在Codex运行的shell中导出`S33K_APIKEY=YOUR_APIKEY`。
### Claude 桌面版
桌面版的配置直接使用stdio，这是本地实例的最佳路径。配置文件：`~/Library/Application Support/Claude/claude_desktop_config.json`（macOS）或`%APPDATA%\Claude\claude_desktop_config.json`（Windows）：
```json
{
"mcpServers": {
"s33k": {
"command": "node",
"args": ["/绝对路径/到/s33k/mcp/dist/index.js"],
"env": { "S33K_API_KEY": "YOUR_APIKEY", "S33K_BASE_URL": "http://localhost:3000" }
}
}
}
```
要访问远程HTTP实例，桌面版需要`mcp-remote`桥：设置`"command": "npx"`和`"args": ["mcp-remote", "https://YOUR_S33K_URL/api/mcp", "--header", "Authorization: Bearer YOUR_APIKEY"]`。
### 高级：网页聊天客户端
**ChatGPT** 可以连接，但前提是s33k可以在 **公共HTTPS URL** 上访问（localhost无效，因为请求来自OpenAI的服务器）。在付费计划上，开启设置中的开发者模式，添加一个自定义连接器，指向`https://YOUR_PUBLIC_S33K_URL/api/mcp`，并提供Bearer密钥。首先将s33k部署到公共位置（参见上面的云部署按钮）。
**Claude Cowork / claude.ai 自定义连接器当前不支持：** 它们的连接器仅接受OAuth 2.1，且没有用于静态Bearer密钥的字段，因此无法输入s33k的单密钥模型。请改用Claude Code或Claude Desktop。
完整工具详情见[`mcp/README.md`](mcp/README.md)。
## 连接Google Search Console（可选）
要通过`get_insight`工具读取Search Console数据，请在`.env`中设置`GSC_OAUTH_CLIENT_ID`、`GSC_OAUTH_CLIENT_SECRET`和`NEXT_PUBLIC_APP_URL`，然后使用“连接Google Search Console”流程。当这些变量未设置时，连接步骤返回友好的“未配置”消息，而不是失败，因此这是完全可选的。
## 排名变化邮件（可选）
s33k可以在跟踪的排名发生变化时通过电子邮件通知您。在应用程序UI的设置中启用它：设置您的SMTP服务器、端口、用户名、密码和通知的发件人和收件人地址（它们在数据库中加密存储，而不是在环境变量中）。使用`NOTIFICATION_INTERVAL`环境变量设置电子邮件间隔（默认为`never`）。排名抓取间隔使用`SCRAPE_INTERVAL`设置。
## 在服务器上托管
要在您的LLM和团队可以访问的服务器上运行s33k（一个小型VPS或服务器），请通过将`DATABASE_URL`设置为`postgresql://...`连接字符串来运行它。s33k在设置`DATABASE_URL`时自动选择Postgres，在未设置时选择SQLite。在Postgres上，应用架构使用`npm run db:migrate`（它使用生产配置针对`DATABASE_URL` Postgres实例运行）。参见[`DEPLOY.md`](DEPLOY.md)获取部署配方，[`CLAUDE.md`](CLAUDE.md)获取数据库缝合和艰难的部署笔记。
## 安全和信任
s33k是无cookie的，不捕获PII，从不训练您的数据，并且不进行服务器端LLM调用。AI功能（`briefing`、`insights`、`ai_visibility`、`alerts`、`entry_pages`）是基于规则的：它们从您自己的数据中计算结构化结果，并将它们交给您自己的LLM来叙述。您可以导出s33k保存的所有内容作为单个JSON包（`export_data`）进行备份，并且由于您是自托管的，因此删除您的数据是一个本地操作：删除您的SQLite文件或Postgres数据库。每个信任声明都指向代码或测试来证明它。参见[`SECURITY.md`](SECURITY.md)，或通过`security_facts`MCP工具询问您自己的LLM。
## 贡献者仓库导向
[`CLAUDE.md`](CLAUDE.md)是任何人（人类或AI）在仓库中工作的标志：运行时和命令、数据库缝合（生产环境为Postgres，本地为SQLite）、艰难的部署问题和无服务器端LLM不变式。
## 许可证
MIT，从SerpBear分支继承。参见[`LICENSE`](LICENSE)。
