Blueprince MCP

蓝王子MCP-建筑师笔记

Blue Prince MCP Architect Notes logo

此存储库包含MCP（模型上下文协议）服务器的代码，该服务器被设计为专用的扰流板、笔记工具和头脑风暴助手，用于玩游戏 蓝色王子.

此MCP服务器公开了用于管理本地笔记（存储为.md文件）的工具和资源，允许用户在玩视频游戏《蓝王子》时写笔记、从笔记中查找信息，并与配套的MCP客户端进行头脑风暴。这是为了帮助玩家建立联系，回忆他们所看到和经历的事情，同时避免在线资源的剧透。

⚠️ 重要：扰流板使用

此MCP服务器旨在保留您的“蓝王子”游戏体验。当与MCP客户端（例如Claude Desktop）一起使用时：

• 主要来源：客户优先考虑您笔记中的信息
• 已过滤的外部访问：客户可以使用外部蓝王子知识，但仅限于您已经发现的内容
• 扰流板保护：过滤外部信息，仅显示您在笔记中记录的内容
• 需要同意：客户在分享可能破坏外部信息之前，会征求许可
• 智能过滤：自动扰流板预防规则作为MCP资源提供
• 发现保护：重点仍然放在你记录在案的经历和发现上

特性

• MCP服务器： 实现MCP协议，将记笔记功能作为工具和资源公开。
• 本地保险库存储： 将笔记作为markdown文件存储在结构化的本地目录中（与Obsidian兼容）。
• 结构化注释： 按预定义类别组织笔记(people, puzzles, rooms, items, lore, general)具有智能元数据提取功能。
• 资源系统： 将所有vault文件作为MCP资源公开，供AI客户端直接访问（不包括 .obsidian/ 目录）。
• 扰流板感知保护系统： 智能过滤，在保留发现的同时启用有用的上下文：

- 动态扰流板预防规则自动作为MCP资源公开 - 通过工具描述和服务器元数据进行客户端执行 - 对所有内容创建进行服务器端验证，并保留发现 - 根据用户记录的发现自动过滤外部信息 - 基于同意的共享可能破坏外部信息 - 内置内容验证，防止过早的调查提示

• 智能笔记和组织：

- ✅ list_notes -列出vault中的所有注释 - ✅ create_note -创建具有智能分类和防扰流板功能的结构化笔记 - ✅ read_note -读取包括元数据在内的完整笔记内容 - ✅ update_note -用新内容更新现有笔记 - 📋 delete_note -计划未来实施

• 智能截图管理与分析（进行中）

- 📋 analyze_screenshot -利用MCP主机分析img文件的内容 - 📋 view_screenshot -显示图像 - 📋 download_screenshots -与Google Drive集成以下载屏幕截图

• CLI测试工具： 用于手动测试和调试的全面命令行界面。
• 安装实用程序： Go程序初始化vault目录结构和配置，以及使用OAuth和Google Drive进行屏幕截图同步。
• 灵活配置： 支持基于文件的配置和环境变量重写。

使用指南

"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代理或测试工具）
• Git

设置

1. 克隆存储库：

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

1. 运行安装实用程序：

此程序将创建必要的黑曜石保管库目录结构，并更新您的 config.yaml 使用vault的路径创建文件。

默认情况下，它将在以下位置创建vault ~/Documents/blueprince_mcp/.

   bin/setup

或者，您可以为vault指定自定义路径：

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

安装实用程序将确保所需的子目录(notes/people, notes/puzzles, notes/rooms, notes/items, notes/lore, notes/general)存在于保险库中，以及 meta/ 和 screenshots/ 目录。

1. 配置Google云端硬盘集成（可选）：

在我部署并托管它之前，要在本地运行，你必须从谷歌云平台获得自己的API证书。 有关更多信息，请参阅以下部分。

一旦你有了证书。/.rentials.json，运行驱动器设置命令：

   bin/setup drive "YourFolderName"

这将：

- 打开浏览器进行Google Drive OAuth身份验证 - 在Google云端硬盘中创建或访问指定文件夹 - 配置查看、编辑、创建和下载文件的权限 - 在本地保存身份验证令牌以备将来使用

要求：

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

1. 审查 config.yaml:

安装实用程序更新 config.yaml 随着 obsidian_vault_path。您可以查看此文件并调整其他设置，如 server.host 或 server.port 如果需要的话。

   # Example config.yaml
   server:
     host: "localhost"
     port: 8001

   obsidian_vault_path: "/Users/michael.myung/Documents/blueprince_mcp" # This will be set by the setup script
   backup_dir_name: ".obsidian_backup" # Directory name for potential future backups within the vault

Google Cloud OAuth应用程序设置

1. 转到Google Cloud控制台： https://console.cloud.google.com/

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

1. 启用必要的API： 在“API和服务”面板中，确保启用该项目所需的特定API（例如，Google Drive API、Gmail API等）。

1. 创建OAuth凭据：

- 转到“API和服务”>“凭据”。 - 点击“+CREATE CREDENTIALS”并选择“OAuth客户端ID”。 - 选择“Web应用程序”作为应用程序类型。 - 在“授权重定向URI”下，添加 http://localhost:8080 （或本地开发服务器使用的任何URI）。 - 单击“创建”。

1. 下载您的凭据：

- 创建客户端ID后，弹出窗口将显示您的客户端ID和客户端密码。您还可以找到您的凭据并单击 下载JSON 新客户端ID右侧的图标。

1. 设置您的本地凭据文件：

- 下载的文件可能会被命名 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连接。

环境配置

可以使用环境变量替代vault路径：

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

Claude桌面集成

请参阅 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

看 cmd/tools/README.md 获取详细的CLI文档和示例。

项目结构

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服务器框架 - 资源系统将所有vault文件暴露给AI客户端 - 具有元数据和类别的结构化笔记模式 - 完成CRUD操作： list_notes, create_note, read_note, update_note, delete_note - Vault目录结构和设置实用程序

• 谷歌云端硬盘集成：

- OAuth2身份验证流程，自动打开浏览器 - 完整的Google Drive API权限（查看、列出、编辑、创建、下载） - 在中保护本地令牌存储 ~/.blueprince_mcp/ - 自动文件夹创建和访问验证 - 注重隐私的设计，无需第三方数据传输 - 重构架构： - 模块化存储接口 runtime/storage/drive 后端 - 集中式Google Drive实用程序和路径管理 - 共享凭据加载和令牌管理 - 设置和运行时操作之间的清晰分离

• 代码质量和测试：

- 全面的单元测试覆盖率 所有主要组件 - 存储实用程序测试（路径管理、令牌处理、配置） - 文件操作测试（安全验证、目录管理） - 身份验证流测试（OAuth设置、错误处理） - 外部依赖关系的模拟实现 - 性能验证的基准测试

• 安全性和可靠性：

- 多层扰流板防护系统 - 路径安全和遍历预防 - 输入验证和错误处理 - 支持环境变量的配置管理

📋 计划的

• 增强的截图集成：

- 智能解读屏幕截图，创建带有图像标签和描述的笔记 - 嵌入带有相关图像智能链接的笔记 - 将图像传回MCP客户端 - ✅ Google Drive同步基础完成 -已准备好从Steam Deck同步截图->谷歌云端硬盘->本地保险库 - 从配置的Google Drive文件夹自动下载和同步文件

贡献

欢迎投稿！请随时打开问题或提交pull请求。

许可证

此项目根据MIT许可证获得许可-有关详细信息，请参阅许可证文件。