AI导哈

游戏笔记管理协议服务器

Blue Prince MCP是一个专为游戏设计的笔记管理协议服务器，提供本地笔记存储、智能分类和防剧透保护功能，帮助玩家记录和整理游戏中的发现。

  • by myungbeans
  • Go
  • 本地部署
  • 2 星标
  • 更新于
在 GitHub 查看 myungbeans/blueprince-mcp

使用说明

蓝王子MCP-建筑师笔记

此存储库包含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

  2. 运行安装实用程序： 此程序将创建必要的黑曜石保管库目录结构，并更新您的 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/ 目录。

  3. 配置Google云端硬盘集成（可选）： 在我部署并托管它之前，要在本地运行，你必须从谷歌云平台获得自己的API证书。 有关更多信息，请参阅以下部分。

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

    bin/setup drive "YourFolderName"

    这将：

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

    要求：

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

  4. 审查 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/

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

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

  4. 创建OAuth凭据：

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

  5. 下载您的凭据：

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

  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连接。

环境配置

可以使用环境变量替代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许可证获得许可-有关详细信息，请参阅许可证文件。

相关 MCP