Blue Prince Architect Notes (MCP Server)

Blue Prince MCP - 建筑师笔记

此仓库包含一个 MCP（Model Context Protocol）服务的代码，旨在作为专用的剧透屏障、笔记工具和头脑风暴助手，帮助玩家游玩游戏 Blue Prince。

此 MCP 服务提供用于管理本地笔记（以 .md 文件形式存储）的工具和资源，让用户能够记笔记、查询笔记中的信息，并在游玩电子游戏 Blue Prince 时与配套的 MCP 客户端一起进行头脑风暴。此服务旨在帮助玩家建立联系，并回想起自己见过和经历过的事情，同时避免从在线资源中看到剧透。

⚠️ 重要：注意剧透的使用方式

此 MCP 服务旨在保护你游玩 Blue Prince 的体验。与 MCP 客户端（例如 Claude Desktop）搭配使用时：

• 主要信息来源：客户端优先使用你笔记中的信息
• 经过筛选的外部访问：客户端可以使用外部 Blue Prince 知识，但仅限你已发现的内容
• 剧透保护：外部信息经过筛选，只显示你在笔记中记录的内容
• 需要征求同意：分享可能包含剧透的外部信息前，客户端会征求你的许可
• 智能筛选：MCP 资源提供自动防剧透规则
• 保留探索体验：重点始终放在你记录的经历和发现上

功能

• **MCP 服务：**实现 MCP 协议，将记笔记功能作为工具和资源提供。
• **本地知识库存储：**将笔记以 Markdown 文件形式存储在结构化的本地目录中（兼容 Obsidian）。
• **结构化笔记：**使用预定义类别（people、puzzles、rooms、items、lore、general）整理笔记，并智能提取元数据。
• **资源系统：**将知识库中的所有文件作为 MCP 资源提供，供 AI 客户端直接访问（不包括 .obsidian/ 目录）。
• **注意剧透的保护系统：**通过智能筛选，在保留探索体验的同时提供有用的上下文：
  • 自动将动态防剧透规则作为 MCP 资源提供
  • 通过工具描述和服务元数据在客户端强制执行
  • 对所有内容创建进行服务端验证，同时保留探索体验
  • 根据用户记录的发现自动筛选外部信息
  • 基于用户同意分享可能包含剧透的外部信息
  • 内置内容验证，防止过早出现调查提示
• 智能记笔记与整理：
  • ✅ list_notes - 列出知识库中的所有笔记
  • ✅ create_note - 创建结构化笔记，并进行智能分类和防剧透处理
  • ✅ read_note - 读取完整笔记内容，包括元数据
  • ✅ update_note - 使用新内容更新现有笔记
  • 📋 delete_note - 计划在未来实现
• 智能截图管理与分析（进行中）
  • 📋 analyze_screenshot - 借助 MCP Host 分析 img 文件的内容
  • 📋 view_screenshot - 显示 img
  • 📋 download_screenshots - 集成 Google Drive 以下载截图
• **CLI 测试工具：**提供全面的命令行界面，用于手动测试和调试。
• **设置工具：**Go 程序，用于初始化知识库目录结构和配置，以及设置与 Google Drive 的 OAuth，以同步截图。
• **灵活配置：**支持基于文件的配置和环境变量覆盖。

使用指南

"Write a new note. I'm in the corridor. There is a painting of a tiger and a cupcake stand(?). Three windows. Two benches and hats."

MCP 客户端随后会智能地设置笔记格式并添加合适的标签。

未来，你可以询问

"Where have I seen windows before? Can you list all rooms that have windows in them?"

MCP 客户端随后会扫描你的所有笔记（且只扫描你的笔记），查找你所知道的所有带窗户的房间。

开始使用

前提条件

• Go（建议使用 1.20 或更高版本）
• MCP 客户端（例如，兼容的 AI Agent 或测试工具）
• Git

设置

1. 克隆仓库：

   git clone https://github.com/myungbeans/blueprince-mcp.git
   cd blueprince-mcp
   

2. 运行设置工具： 此程序会创建必要的 Obsidian 库目录结构，并使用库的路径更新 config.yaml 文件。

   默认情况下，它会在 ~/Documents/blueprince_mcp/ 创建库。

   bin/setup
   

   或者，你可以为库指定自定义路径：

   bin/setup /path/to/your/custom/vault
   

   设置工具会确保库中存在所需的子目录（notes/people、notes/puzzles、notes/rooms、notes/items、notes/lore、notes/general），以及 meta/ 和 screenshots/ 目录。

3. 配置 Google Drive 集成（可选）： 在我完成部署并托管此项目之前，要在本地运行，你必须从 Google Cloud Platform 获取自己的 API 凭据。 更多信息请参阅下文。

   在 ./.credentials.json 中准备好凭据后，运行 Drive 设置命令：

   bin/setup drive "YourFolderName"
   

   此命令将：

   • 打开浏览器，进行 Google Drive OAuth 身份验证
   • 在你的 Google Drive 中创建或访问指定文件夹
   • 配置查看、编辑、创建和下载文件的权限
   • 在本地保存身份验证令牌，供日后使用

   要求：

   • 必须指定文件夹名称（不能是根目录）
   • Google Drive 权限包括：查看、列出、编辑、创建目录和下载文件
   • 所有身份验证数据都存储在你的本地计算机上。有关数据处理的详情，请参阅我们的隐私政策

4. 检查 config.yaml： 设置工具会使用 obsidian_vault_path 更新 config.yaml。你可以检查此文件，并根据需要调整 server.host 或 server.port 等其他设置。

   # config.yaml 示例
   server:
     host: "localhost"
     port: 8001
   
   obsidian_vault_path: "/Users/michael.myung/Documents/blueprince_mcp" # 此值将由设置脚本设置
   backup_dir_name: ".obsidian_backup" # 库中用于未来可能进行的备份的目录名称
   

Google Cloud OAuth 应用设置

1. 前往 Google Cloud Console： https://console.cloud.google.com/

2. 创建新项目： 如果你还没有项目，请创建一个新项目。

3. 启用所需的 API： 在“APIs & Services”信息中心中，确保启用此项目所需的特定 API（例如 Google Drive API、Gmail API 等）。

4. 创建 OAuth 凭据：

   • 前往“APIs & Services” > “Credentials”。
   • 点击“+ CREATE CREDENTIALS”，并选择“OAuth client ID”。
   • 将应用类型选为“Web application”。
   • 在“Authorized redirect URIs”下，添加 http://localhost:8080（或本地开发服务器使用的 URI）。
   • 点击“Create”。

5. 下载凭据：

   • 创建客户端 ID 后，弹出窗口会显示你的 Client ID 和 Client Secret。你也可以找到凭据，然后点击新客户端 ID 右侧的 Download JSON 图标。

6. 设置本地凭据文件：

   • 下载的文件可能名为 client_secret_XXXXXXXX.json。
   • 将此文件重命名为 .credentials.json。
   • 将此 .credentials.json 文件放在此项目的根目录中。

   或者，你可以将 credentials.example.json 文件复制为名为 .credentials.json 的新文件，并将客户端 ID 和客户端密钥粘贴到相应字段中。

构建与使用

构建服务端

go build -o ./bin/blueprince-mcp-server ./cmd/server/main.go

构建 CLI 工具

go build -o ./bin/blueprince-tools ./cmd/tools/

构建设置工具

go build -o ./bin/setup ./cmd/setup/main.go

运行服务

本地开发

确保你位于项目根目录。

go run ./cmd/server/main.go

服务将启动，并通过 stdio 传输监听 MCP 连接。

环境配置

你可以使用环境变量覆盖知识库路径：

OBSIDIAN_VAULT_PATH=/path/to/vault go run ./cmd/server/main.go

Claude Desktop 集成

请参阅Claude Desktop 添加自定义 MCP 服务的说明

简而言之 根据需要进行编辑，并将以下内容添加到 Claude Desktop 配置中：

{
  "mcpServers": {
    "blueprince-notes": {
      "command": "/path/to/blueprince-mcp/bin/blueprince-mcp-server",
      "env": {
        "GOOGLE_DRIVE_SECRETS_DIR": "/Users/yourprofile/.blueprince_mcp",
        "GOOGLE_DRIVE_SCREENSHOT_FOLDER": "Blue Prince",
        "OBSIDIAN_VAULT_PATH": "/path/to/your/vault",
        "ROOT": "/path/to/repo/blueprince-mcp"
      }
    }
  }
}

请务必更新你的 /path/to 路径

使用 CLI 工具进行测试

项目包含一套全面的 CLI，可用于手动测试：

# List all notes
./bin/blueprince-tools list

# Create a new note
./bin/blueprince-tools create people/character.md \
  --title "Character Name" \
  --content "Character description"

# Read a note
./bin/blueprince-tools read people/character.md

# Update a note
./bin/blueprince-tools update people/character.md \
  --content "Updated character information"

# Use verbose mode for debugging
./bin/blueprince-tools list --verbose

有关 CLI 的详细文档和示例，请参阅 cmd/tools/README.md。

项目结构

blueprince-mcp/
├── runtime/
│   ├── mcp/
│   │   ├── tools/              # MCP Tool implementations
│   │   └── resources/          # MCP Resources
│   ├── models/
│   │   ├── notes/              # Note structure and schemas
│   │   ├── vault/              # Obsidian Vault constants and structure
│   │   └── storage/            # Storage interface abstractions
│   ├── storage/                # Storage implementations
│   │   └── drive/              # Google Drive implementation
│   └── utils/                  # Common utilities (logging, file ops, security)
├── cmd/
│   ├── server/main.go          # Main MCP server application
│   ├── setup/                  # Setup utilities
│   ├── tools/                  # CLI for running MCP Server Tools locally
│   └── config/                 # Configuration management
├── docs/                       # Documentation for GitHub Pages
└── bin/                        # Built binaries

当前状态与路线图

✅ 已完成

• 核心 MCP 框架：
  • 采用 stdio 传输的 MCP 服务框架
  • 资源系统，可向 AI 客户端公开所有知识库文件
  • 带有元数据和分类的结构化笔记架构
  • 完整的 CRUD 操作：list_notes、create_note、read_note、update_note、delete_note
  • 知识库目录结构和设置工具
• Google Drive 集成：
  • OAuth2 身份验证流程，并自动打开浏览器
  • 完整的 Google Drive API 权限（查看、列出、编辑、创建、下载）
  • 在 ~/.blueprince_mcp/ 中安全存储本地令牌
  • 自动创建文件夹并验证访问权限
  • 注重隐私的设计，不会向第三方传输数据
  • 重构后的架构：
    • 模块化存储接口，采用 runtime/storage/drive 后端
    • 集中管理 Google Drive 工具和路径
    • 共享凭据加载和令牌管理
    • 清晰分离设置操作和运行时操作
• 代码质量与测试：
  • 全面覆盖所有主要组件的单元测试
  • 存储工具测试（路径管理、令牌处理、配置）
  • 文件操作测试（安全验证、目录管理）
  • 身份验证流程测试（OAuth 设置、错误处理）
  • 外部依赖的模拟实现
  • 用于性能验证的基准测试
• 安全性与可靠性：
  • 多层防剧透系统
  • 路径安全与路径遍历防护
  • 输入验证和错误处理
  • 支持环境变量的配置管理

📋 计划中

• 增强截图集成：
  • 智能解读截图，创建带有图像标签和描述的笔记
  • 在笔记中嵌入指向相关图像的智能链接
  • 将图像提供给 MCP 客户端
  • ✅ Google Drive 同步基础功能已完成——已准备好从 Steam Deck 同步截图到 Google Drive，再同步到本地知识库
  • 自动下载并同步已配置 Google Drive 文件夹中的文件

贡献

欢迎贡献！请随时提交问题或拉取请求。

许可证

本项目采用 MIT 许可证授权，详情请参阅 LICENSE 文件。