mcp-construe

一个FastMCP服务器，从Obsidian保险库中加载个人上下文信息，使用frontmatter过滤器——整理你的知识以供AI对话使用。

功能

• 双向知识管理：读取和写入你的Obsidian保险库
• 智能分块：自动分割大型结果集，以保持在上下文限制内（每个分块95k字符）
• 灵活过滤：通过frontmatter属性和标签进行搜索，支持AND/OR逻辑
• 文件保护：安全控制防止在指定上下文之外覆盖文件
• Frontmatter集成：正确生成和解析YAML frontmatter

使用方法

基本用法

python3 mcp-construe.py

自定义配置

python3 mcp-construe.py --config other-config.yaml
python3 mcp-construe.py --config /path/to/custom-config.yaml

配置

在同一目录下创建一个config.yaml文件：

# 你的Obsidian保险库路径（支持~表示主目录）
vault_path: "/path/to/obsidian/vault"

# fetch_context()的默认上下文标准
default_context:
  properties:
    context: "personal"
  tags: []

# 保护设置：仅允许创建或覆盖具有此属性值的文件
# MCP服务器只能创建具有此属性的文件，并且只能覆盖
# 具有此属性设置为这些值之一的文件
protection_property: "author"     # 要检查的frontmatter属性
protection_value: ["claude"]      # 允许的值（支持单个字符串或列表）

工具

上下文加载工具

• fetch_context(context_type, chunk_index=0) - 按上下文类型加载文件，支持分块
• fetch_matching_files(properties, tags, match_all_tags, chunk_index=0) - 灵活过滤，支持分块
• fetch_frontmatter_index(properties, tags, match_all_tags, chunk_index=0, max_chars=95000) - 浏览文件元数据，支持分页

分块管理工具

• list_context_chunks(context_type, max_chars=95000) - 列出上下文类型的可用分块
• list_matching_chunks(properties, tags, match_all_tags, max_chars=95000) - 列出自定义搜索的分块
• fetch_context_chunk(context_type, chunk_index, max_chars=95000) - 根据上下文获取特定分块
• fetch_matching_chunk(chunk_index, properties, tags, match_all_tags, max_chars=95000) - 根据条件获取特定分块

文件创建工具

• create_file(filename, content, properties, tags, subfolder="", overwrite=False) - 创建带有frontmatter的新文件

安全功能

文件保护系统

服务器包含强大的保护机制，防止未经授权的文件修改：

1. 双重验证：创建新文件和覆盖现有文件都必须具有所需的保护属性
2. 灵活属性控制：可以配置任何frontmatter属性（例如author、context、owner）作为保护键
3. 多个允许值：支持多个有效值（例如["claude", "assistant"]）
4. 全面覆盖：所有文件写操作均受保护

示例保护场景

配置：protection_property: "author"，protection_value: ["claude"]

✅ 允许：

# 创建具有所需属性的新文件
create_file("note.md", "content", properties={"author": "claude"})

# 覆盖具有作者：claude的现有文件
create_file("existing.md", "new content", properties={"author": "claude"}, overwrite=True)

❌ 阻止：

# 缺少所需属性
create_file("note.md", "content", properties={})

# 错误的属性值
create_file("note.md", "content", properties={"author": "unauthorized"})

# 尝试覆盖具有不同作者的文件
# （现有文件的作者是human，配置要求作者是claude）

分块行为

当搜索结果超过95k字符限制时，系统会自动对结果进行分块：

1. 使用列出工具查看可用分块：list_context_chunks() 或 list_matching_chunks()
2. 使用分块工具或chunk_index参数获取特定分块
3. 文件永远不会被分割 - 每个分块只包含完整的文件
4. 当存在多个分块时自动警告

示例Frontmatter

文件应包含适当的YAML frontmatter以便于过滤：

---
author: claude
context: personal
type: note
tags: [ai, productivity, tools]
created: 2024-01-15
---

# 这里是你的内容

此笔记将由MCP服务器发现。

安装

1. 克隆仓库
2. 安装依赖项：pip install fastmcp pyyaml pathlib
3. 配置你的config.yaml
4. 运行：python3 mcp-construe.py

更新日志

2025-09-15

• 添加了分页到fetch_frontmatter_index：添加了chunk_index和max_chars参数，以防止LLM消息大小限制问题
• 改进了大型结果处理：frontmatter索引函数现在自动对大型结果集进行分块，以提高性能
• 增强了API一致性：所有浏览功能现在遵循相同的分块模式

许可证

详情见LICENSE文件。