蓝王子-mcp
项目介绍
Blue Prince MCP - 架构说明
此仓库包含一个MCP（模型上下文协议）服务器的代码，该服务器旨在作为游戏《Blue Prince》的专用剧透防护、笔记工具和头脑风暴助手。
此MCP服务器提供了管理本地笔记（以.md文件形式存储）的工具和资源，允许用户在玩《Blue Prince》视频游戏时撰写笔记、查找信息并使用伴随的MCP客户端进行头脑风暴。这旨在帮助玩家建立联系并回忆他们在游戏中看到和经历的事情，同时避免从在线资源中获取剧透。
⚠️ 重要提示：注意剧透
此MCP服务器旨在保护您的《Blue Prince》游戏体验。当与MCP客户端（例如Claude Desktop）一起使用时：
- 主要来源：客户端优先使用您的笔记中的信息
- 过滤外部访问：客户端可以使用外部《Blue Prince》知识，但仅限于您已经发现的内容
- 剧透保护：外部信息被过滤，只显示您在笔记中记录的内容
- 需要同意：客户端会在分享可能剧透的外部信息前请求许可
- 智能过滤：提供自动剧透预防规则作为MCP资源
- 发现保护：重点放在您的记录经验和发现上
功能
- MCP服务器：实现MCP协议，暴露笔记功能作为工具和资源。
- 本地保险库存储：将笔记存储为结构化的本地目录中的markdown文件（兼容Obsidian）。
- 结构化笔记：按预定义类别（
人物，谜题，房间，物品，背景故事，通用）组织笔记，并提取智能元数据。 - 资源系统：将所有保险库文件暴露为MCP资源，供AI客户端直接访问（排除
.obsidian/目录）。 - 注意剧透的保护系统：智能过滤，在保护发现的同时提供有用的上下文：
- 动态剧透预防规则自动作为MCP资源暴露
- 客户端通过工具描述和服务器元数据执行过滤
- 服务器验证所有内容创建，确保发现保护
- 根据用户的记录发现自动过滤外部信息
- 基于同意分享可能剧透的外部信息
- 内置内容验证，防止过早调查提示
- 智能笔记记录与组织：
- ✅
列出笔记- 列出保险库中的所有笔记 - ✅
创建笔记- 创建具有智能分类和剧透预防的结构化笔记 - ✅
阅读笔记- 阅读完整的笔记内容，包括元数据 ️更新笔记- 更新现有笔记的新内容 - 📋
删除笔记- 计划未来实现
- ✅
- 智能截图管理和分析（正在进行中）
- 📋
分析截图- 利用MCP主机分析img文件的内容 - 📋
查看截图- 显示img - 📋
下载截图- 与Google Drive集成以下载截图
- 📋
- 命令行测试工具：全面的命令行界面用于手动测试和调试。
- 设置实用程序：Go程序初始化保险库目录结构和配置，以及与Google Drive的OAuth同步截图。
- 灵活配置：支持基于文件的配置和环境变量覆盖。
使用指南
“写一篇新笔记。我在走廊里。有一幅老虎的画和一个纸杯蛋糕摊位（？）。三个窗户。两个长凳和帽子。”
然后，MCP客户端会智能地格式化笔记并适当标记它。
将来，您可以询问
“我以前在哪里见过窗户？你能列出所有有窗户的房间吗？”
然后，MCP客户端将扫描您的所有笔记（仅限您的笔记），查找您知道的所有有窗户的房间。
开始使用
先决条件
- Go（推荐版本1.20或更高）
- 一个MCP客户端（例如，兼容的AI代理或测试工具）
- Git
设置
-
克隆仓库：
git clone https://github.com/myungbeans/blueprince-mcp.git cd blueprince-mcp -
运行设置实用程序： 此程序将创建必要的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/目录。 -
配置Google Drive集成（可选）： 在部署和托管之前，要本地运行，您必须从Google Cloud Platform获取自己的API凭据。 请参阅以下部分了解更多信息。
您有了凭据后（位于
./.credentials.json），运行驱动器设置命令：bin/setup drive "YourFolderName"这将：
- 打开浏览器进行Google Drive OAuth身份验证
- 创建或访问您Google Drive中的指定文件夹
- 配置查看、编辑、创建和下载文件的权限
- 将认证令牌保存到本地以备将来使用
要求：
- 文件夹名称必须指定（不能是根目录）
- Google Drive权限包括：查看、列表、编辑、创建目录、下载文件
- 所有认证数据都存储在您的机器上。有关数据处理详情，请参阅我们的隐私政策
-
检查
config.yaml： 设置实用程序更新了config.yaml中的obsidian_vault_path。您可以检查此文件并根据需要调整其他设置，如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应用设置
- 前往Google Cloud控制台： https://console.cloud.google.com/
- 创建新项目： 如果您还没有项目，请创建一个新项目。
- 启用必要的API： 在“API和服务”仪表板中，确保启用该项目所需的具体API（例如，Google Drive API，Gmail API等）。
- 创建OAuth凭证：
- 转到“API和服务”>“凭证”。
- 点击“+ 创建凭证”并选择“OAuth客户端ID”。
- 选择“网络应用”作为应用程序类型。
- 在“授权重定向URI”下，添加
http://localhost:8080（或您本地开发服务器使用的任何URI）。 - 点击“创建”。
- 下载您的凭证：
- 创建客户端ID后，弹出窗口将显示您的客户端ID和客户端密钥。您也可以找到您的凭证并点击右侧的新客户端ID的下载JSON图标。
- 设置本地凭证文件：
- 下载的文件可能命名为
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
构建命令行工具
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用于手动测试：
# 列出所有笔记
./bin/blueprince-tools list
# 创建新笔记
./bin/blueprince-tools create people/character.md \
--title "角色名称" \
--content "角色描述"
# 阅读笔记
./bin/blueprince-tools read people/character.md
# 更新笔记
./bin/blueprince-tools update people/character.md \
--content "更新的角色信息"
# 使用详细模式进行调试
./bin/blueprince-tools list --verbose
请参阅cmd/tools/README.md以获取详细的CLI文档和示例。
项目结构
blueprince-mcp/
├── runtime/
│ ├── mcp/
│ │ ├── tools/ # MCP工具实现
│ │ └── resources/ # MCP资源
│ ├── models/
│ │ ├── notes/ # 笔记结构和模式
│ │ ├── vault/ # Obsidian保险库常量和结构
│ │ └── storage/ # 存储接口抽象
│ ├── storage/ # 存储实现
│ │ └── drive/ # Google Drive实现
│ └── utils/ # 常用工具（日志记录、文件操作、安全）
├── cmd/
│ ├── server/main.go # 主MCP服务器应用程序
│ ├── setup/ # 设置实用程序
│ ├── tools/ # 本地运行MCP服务器工具的CLI
│ └── config/ # 配置管理
├── docs/ # GitHub Pages文档
└── bin/ # 构建的二进制文件
当前状态与路线图
✅ 已完成
- 核心MCP框架：
- 带有stdio传输的MCP服务器框架
- 资源系统将所有保险库文件暴露给AI客户端
- 带有元数据和类别的结构化笔记模式
- 完整的CRUD操作：
列出笔记，创建笔记，阅读笔记，更新笔记，删除笔记 - 保险库目录结构和设置实用程序
- 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文件。