MCP Construe

mcp解释

FastMCP服务器使用frontmatter过滤从黑曜石保险库加载个人上下文，为人工智能对话整理您的知识。

特性

• 双向知识管理：读写你的黑曜石金库
• 智能分块：自动拆分大型结果集以保持在上下文限制内（每个块95k个字符）
• 灵活过滤：使用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 文件与脚本位于同一目录中：

# Path to your Obsidian vault (supports ~ for home directory)
vault_path: "/path/to/obsidian/vault"

# Default context criteria for fetch_context()
default_context:
  properties:
    context: "personal"
  tags: []

# Protection settings: Only allow creating/overwriting files with this property value
# The MCP server can only create files with this property, and can only overwrite
# files that have this property set to one of these values
protection_property: "author"     # which frontmatter property to check
protection_value: ["claude"]      # allowed values (supports single string or list)

工具

上下文加载工具

• fetch_context（context_type，chunk_index=0） -使用分块支持按上下文类型加载文件
• fetch_matching_files（属性、标签、match_all_tags、chunk_index=0） -灵活的分块过滤
• fetch_frontmatter_index（属性、标签、match_all_tags、chunk_index=0、max_chars=95000） -使用分页浏览文件元数据

分块管理工具

• list_context_chunks（context_type，max_chars=95000） -列出上下文类型的可用块
• list_matching_chunks（属性、标签、match_all_tags、max_chars=95000） -列出自定义搜索的块
• fetch_context_chunk（context_type，chunk_index，max_chars=95000） -按上下文获取特定块
• fetch_matching_chunk（chunk_index、属性、标签、match_all_tags、max_chars=95000） -根据条件获取特定块

文件创建工具

• create_file（文件名、内容、属性、标签、子文件夹=“”，覆盖=False） -使用frontmatter创建新文件

安全功能

文件保护系统

该服务器包括一个强大的保护机制，可防止未经授权的文件修改：

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

保护场景示例

配置: protection_property: "author", protection_value: ["claude"]

✅ 允许:

# Create new file with required property
create_file("note.md", "content", properties={"author": "claude"})

# Overwrite existing file that has author: claude
create_file("existing.md", "new content", properties={"author": "claude"}, overwrite=True)

❌ 已屏蔽:

# Missing required property
create_file("note.md", "content", properties={})

# Wrong property value  
create_file("note.md", "content", properties={"author": "unauthorized"})

# Attempting to overwrite file with different author
# (existing file has author: human, config requires author: claude)

块状行为

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

1. 使用列表工具 要查看可用块，请执行以下操作： list_context_chunks() 或 list_matching_chunks()
2. 获取特定块 使用组块工具或 chunk_index 参数
3. 文件从不拆分 -每个块仅包含完整的文件
4. 自动警告 当有多个块可用时

前台示例

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

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

# Your Content Here

This note will be discoverable by the MCP server.

安装

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文件。