内容
# OpenFindability
连接 Google 搜索控制台和 Umami 到 Claude Code 工作流的本地 SEO 仪表盘，通过 MCP 实现。
跟踪您的网站项目如何被找到，发现 SEO 机会，并从任何 Claude Code 会话中查询实时分析数据 — 无需构建 SaaS 或大型 monorepo。
## 功能
- **本地 Next.js 仪表盘** — 可视化 GSC + Umami 数据，适用于所有项目
- **MCP 服务器** — 从任何 Claude Code 项目中调用实时 GSC 和 Umami 数据，作为原生工具
- **SEO 机会** — 自动检测低 CTR 查询、临界关键词、 cannibalization 等
- **基于文件的存储** — 单个 JSON 文件，无需数据库
- **演示数据** — 种子数据，探索无需真实凭证
## 快速开始
```bash
pnpm install
pnpm seed:demo
pnpm dev
```
打开 `http://localhost:3000`。
## 引导式设置
按以下顺序进行干净的本地设置：
```bash
pnpm install
cp .env.example .env
pnpm run doctor
pnpm dev
```
然后仅配置您需要的连接器。
### 1. 添加凭证
Google 搜索控制台和 Play 控制台使用 Google 服务账户 JSON 文件。将它放在 `secrets/google/` 下，并指向 `.env`:
```env
GOOGLE_SERVICE_ACCOUNT_FILE=./secrets/google/search-console-service-account.json
```
Umami 只需要 API 基本 URL 和 API 密钥：
```env
UMAMI_BASE_URL=https://api.umami.is/v1
UMAMI_API_KEY=...
```
RespectASO 是可选的，本地的：
```env
RESPECT_ASO_BASE_URL=http://localhost
```
### 2. 添加项目
```bash
pnpm run project:add -- \
--name "示例网站" \
--slug example-site \
--type web \
--url https://example.com/ \
--gsc sc-domain:example.com
```
对于具有 ASO 研究的应用：
```bash
pnpm run project:add -- \
--name "示例应用" \
--slug example-app \
--type app \
--app-store-track-id 1234567890 \
--respect-aso-app-id 3 \
--aso-countries it \
--aso-keywords "主要关键词,次要关键词"
```
### 3. 同步或研究
```bash
pnpm run sync:gsc # 导入搜索控制台数据
pnpm run sync:aso # 导入配置的 RespectASO 关键词
pnpm run report -- example-app all
```
用于商店列表研究的结合 RespectASO 和 GSC 查询语言：
```bash
pnpm run research:aso -- \
--slug example-app \
--gsc-slug example-site \
--url-contains example.com/app \
--query-contains "主要关键词" \
--keywords "主要关键词,次要关键词,线上,离线"
```
研究报告写入 `project/<slug>/reports/`，被 git 忽略。ASO 关键词观察也缓存在 `data/openfindability.json` 中，以便后续研究可以在项目间重用最近的 `keyword + country` 结果。使用 `--refresh` 强制新的 RespectASO 查找。
## MCP 服务器 — 从任何 Claude Code 项目中使用
OpenFindability 公开一个 MCP 服务器，以便 Claude Code 可以从任何仓库实时查询您的分析数据。
### 设置（一次）
全局安装 tsx：
```bash
npm install -g tsx
```
添加到 `~/.claude/settings.json`:
```json
{
"mcpServers": {
"openfindability": {
"command": "tsx",
"args": ["/绝对路径/to/OpenFindability/mcp/server.ts"]
}
}
}
```
在 Windows 上使用 `tsx.cmd` 的完整路径：
```json
{
"mcpServers": {
"openfindability": {
"command": "C:\\Users\\<用户>\\AppData\\Roaming\\npm\\tsx.cmd",
"args": ["C:\\路径\\到\\OpenFindability\\mcp\\server.ts"]
}
}
}
```
重启 Claude Code。服务器自动启动 — 无需保持运行的进程。
### 可用工具
| 工具 | 描述 |
|------|-------------|
| `list_projects` | 列出配置的项目及其 slugs |
| `get_project_summary` | 实时 GSC + Umami + 机会，一次调用 |
| `get_gsc_stats` | 实时 GSC 数据：点击量、展示次数、热门查询、热门页面 |
| `get_umami_stats` | 指定日期的实时 Umami 访问者和页面浏览量 |
| `get_page_keywords` | 特定页面 URL 的所有 GSC 查询排名 |
| `compare_periods` | 比较当前和上一周期的变化 |
| `get_opportunities` | 上次同步的 SEO 机会 |
| `list_gsc_properties` | 服务账户可访问的 GSC 属性 |
| `create_project` | 添加新项目（也创建其文件夹结构） |
| `update_project` | 更新项目字段 |
| `delete_project` | 删除项目及其所有数据 |
实时工具（`get_gsc_stats`、`get_umami_stats`、`get_project_summary`、`get_page_keywords`、`compare_periods`）实时调用 API — 无需同步。
参见 [`docs/guide/mcp-server.md`](docs/guide/mcp-server.md) 获取完整设置和使用方法。
## 配置真实连接器
复制 `.env.example` 到 `.env` 并填写所需的值。
**Google 搜索控制台** — 使用具有访问您搜索控制台属性权限的 Google 服务账户。将 JSON 文件放在 `secrets/google/` 下。
```env
GOOGLE_SERVICE_ACCOUNT_FILE=./secrets/google/search-console-service-account.json
```
或内联：
```env
GOOGLE_SERVICE_ACCOUNT_JSON={...}
```
**Umami：**
```env
UMAMI_BASE_URL=https://api.umami.is/v1
UMAMI_API_KEY=...
```
然后通过 MCP `create_project` 工具或直接编辑 `data/openfindability.json` 添加项目。
## 有用命令
```bash
pnpm run doctor # 检查连接器配置
pnpm seed:demo # 种子演示数据
pnpm run sync # 同步所有连接器
pnpm run sync:gsc # 仅同步 GSC
pnpm run sync:umami # 仅同步 Umami
pnpm typecheck
pnpm build
```
## 同步行为
v0.1 仅使用手动同步。
- GSC 默认导入最近 30 天（搜索控制台数据有约 2 天延迟）。
- Umami 导入昨天的數據。
- 每次导入都保留 `rawJson`。
- 连接器运行记录到 `connectorRuns`。
- 页面级 GSC 数据单独存储，与查询级数据分开。
## 私有文件
这些文件被 git 故意忽略：
```
.env
data/openfindability.json
project/ ← 按项目报告、上下文、备注
private-notes/
secrets/
```
参见 [`docs/operations/sensitive-files.md`](docs/operations/sensitive-files.md) 获取详细信息。
## 许可证
MIT
