Construe

You run a FastMCP server that reads and writes to your Obsidian vault, using frontmatter filtering to tailor knowledge for AI conversations. It automatically chunks large results to stay within context limits and protects files so you only modify designated content.

How to use

Start the MCP server by running the main Python script. The server loads your Obsidian vault, applies your frontmatter filters, and serves results in manageable chunks for conversations with AI.

How to install

Prerequisites you need installed on your system.

pip install fastmcp pyyaml pathlib

Basic run with default config

Run the server with the default configuration file named config.yaml placed in the same directory as the script.

python3 mcp-construe.py

Custom configuration

Use a different configuration file if you want to customize how the MCP server loads data and enforces protections.

python3 mcp-construe.py --config other-config.yaml

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

Configuration specifics

Create a YAML configuration named config.yaml in the same folder as the script and tailor the settings to your environment. The key options include where your Obsidian vault lives, default context criteria for fetch_context, and protection settings that guard file creation and overwrites.

Example configuration content

# 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)

Chunking and large result handling

When result sets exceed the 95k character limit, the system automatically chunks results. You can list available chunks, fetch specific chunks by index, and run operations that ensure files are never split across chunks.

Frontmatter and example

Files should include proper YAML frontmatter for filtering so the MCP server can discover and filter content.

---
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.

Security features

The server includes a robust protection mechanism that prevents unauthorized file modifications. It uses a dual validation process and supports configuring any frontmatter property as the protection key, with multiple allowed values.

Files and creation protection examples

The protection system ensures that new files and overwrites only occur when the required property value is present.

Usage notes

All file write operations are protected. If a file does not contain the required frontmatter property value, creation or overwriting is blocked.

Installation notes

The server uses a simple Python-based workflow. After installation, you run the server as shown above and optionally specify a custom configuration file.

Changelog

Changelog highlights include added pagination to frontmatter indexing and improved handling of large result sets through automatic chunking to prevent message size issues.

License

See the LICENSE file for details.

Available tools

fetch_context

Load files by context type with chunking support.

fetch_matching_files

Filter files by frontmatter properties and tags with AND/OR logic and chunking.

fetch_frontmatter_index

Browse file metadata with pagination and frontmatter filtering.

list_context_chunks

List available context chunks for a given type and size.

list_matching_chunks

List chunks that match specific properties and tags.

fetch_context_chunk

Fetch a specific chunk by context type and index.

fetch_matching_chunk

Fetch a specific chunk by criteria.

create_file

Create new files with proper frontmatter and optional overwrite protection.