内容
# Shelfbound
**为您的真实Steam库准备好AI就绪的上下文**
Shelfbound是一个个人游戏上下文层：它读取您的**真实**Steam库 — 包括每个设备上安装的游戏和（即将支持）您的本地分类、笔记、状态和偏好 — 并通过 [MCP](https://modelcontextprotocol.io) 在本地或托管服务上使其可用于AI工具。这样做的目的是让ChatGPT/Claude能够推理您的**个人**库，而不仅仅是普通的Steam API数据。
> **非官方**。Shelfbound与Valve公司无关联或未获得其认可。"Steam"仅用于描述。
该仓库（`shelfbound-steam`）是**开源本地核心**：领域模型、快照合约、本地Steam扫描器和CLI。托管服务位于单独的私有仓库中。
## 状态
早期但已经很有用，所有功能都在本地：
- **`shelfbound scan`** 编写您库的版本化**快照** — 跨所有库安装的游戏（名称、安装状态、大小、时间戳）、您的Steam账户、设备和**本地分类**（您组织库的集合）。如果有Steam Web API密钥，还会添加**已拥有但未安装的游戏和游戏时间**。不包括安装路径、凭证或存档。
- **`shelfbound-mcp`** — 本地 **MCP服务器**，向AI工具（ChatGPT/Claude）公开库：按类别/安装状态/游戏时间搜索、库摘要、游戏详情、“我还没玩过什么？”。
- **每游戏上下文** — MCP服务器还可以**记住**您告诉它的内容：状态（已完成/暂停/放弃）、评分、完成度、类别含义和自由记忆 — 存储在本地并与CLI共享。
尚未构建：现代动态收藏、账户、上传和托管服务。参见 [docs/project/PROJECT.md](docs/project/PROJECT.md) 了解路线图。
## 快速开始
需要 **.NET 10 SDK**。
```bash
dotnet build
dotnet run --project src/Shelfbound.Cli -- setup # 一次性：显示配置 + 如何添加API密钥
dotnet run --project src/Shelfbound.Cli -- scan --pretty
```
**Steam Web API密钥（可选 — 用于已拥有但未安装的游戏 + 游戏时间）**：在 <https://steamcommunity.com/dev/apikey> 获取一个（登录，注册任意域名 — `localhost` 即可），然后 `shelfbound setup --steam-api-key <key>`。同时将您的Steam个人资料 **游戏详情 → 公共**，否则API返回为空。CLI和MCP服务器都使用保存的密钥。
这会写入 `shelfbound-snapshot.json`（被git忽略 — 它列出了您的游戏，因此请视为个人数据）。有用的选项：`--output <file>`、`--stdout`、`--steam-path <dir>`、`--device-name <name>`、`--device-type …` 和 `--steam-api-key <key>` （或 `STEAM_WEB_API_KEY`）通过Steam Web API添加已拥有但未安装的游戏 + 游戏时间。运行 `shelfbound --help`。
### 本地MCP服务器
`shelfbound-mcp` 在启动时扫描您的库，并通过stdio向MCP兼容的AI客户端提供服务。将您的客户端（例如Claude Desktop）指向编译的 `shelfbound-mcp` 可执行文件。它从环境中读取配置：`SHELFBOUND_STEAM_PATH` （否则自动检测）、`STEAM_WEB_API_KEY` （可选，用于已拥有游戏 + 游戏时间）、`SHELFBOUND_SNAPSHOT` （加载快照文件而不是扫描）。读取工具：`search_library`、`get_library_summary`、`get_categories`、`get_game_details`、`find_installed_unplayed`。写入/记住工具：`record_game_status`、`record_game_opinion`、`set_game_completion`、`set_category_definition`、`remember`，以及 `get_game_user_data` / `get_remembered`。
```bash
dotnet test
```
## 仓库布局
整个仓库在 **AGPL-3.0-or-later** 下获得许可（参见 [License](#license)）。
| 项目 | 目的 |
|---|---|
| `src/Shelfbound.Core` | 领域模型 + 版本化快照合约 + 序列化器。 |
| `src/Shelfbound.Steam` | 本地Steam扫描器 + Steam Web API客户端 + 数据丰富。 |
| `src/Shelfbound.Query` | 基于快照的确定性查询/筛选/摘要引擎。 |
| `src/Shelfbound.Storage` | 本地配置、身份缝隙和用户数据存储（状态、评分、记忆）。 |
| `src/Shelfbound.Cli` | `shelfbound` 命令行工具（设置/扫描/导出）。 |
| `src/Shelfbound.Mcp` | `shelfbound-mcp` 本地MCP服务器。 |
| `tests/…` | 单元测试 + 集成测试。 |
## 文档
从 [docs/project/PROJECT.md](docs/project/PROJECT.md) 开始；快照合约在 [docs/project/snapshot-schema.md](docs/project/snapshot-schema.md) 和 [`schema/snapshot.v0.schema.json`](schema/snapshot.v0.schema.json) 中。
## 许可证
该项目在 **AGPL-3.0-or-later** 下获得许可（参见 [LICENSE](LICENSE)），以确保对托管或修改版本的改进仍然可供用户和社区使用。这使得开源核心对所有人保持免费，并防止它被悄悄地变成一个封闭产品。可能会提供一个单独的托管版本以方便使用；它在私有环境中开发，不在此仓库范围内。
