folios 0.1.0

MCP server for versioned document retrieval, metadata access, and diff capabilities

Folios

A Model Context Protocol (MCP) server for versioned document management. Folios provides AI agents with access to your document library.

Features

• Versioned Documents - Store multiple versions of documents with simple {id}_v{version}.md naming
• Rich Metadata - YAML frontmatter with author, reviewer, approver, status, and type
• Auto-parsed Chapters - H1/H2 headings automatically extracted as document structure
• Version Comparison - Generate diffs between any two versions
• Flexible Filtering - Query documents by status, type, or author

Installation

# Using uvx (recommended)
uvx folios

# Using pip
pip install folios

Quick Start

1. Create your documents folder

Documents follow the naming convention {id}_v{version}.md:

documents/
├── 123456_v1.md
├── 123456_v2.md
└── 789012_v1.md

2. Add YAML frontmatter to each document

---
id: 123456
version: 1
title: "Stress Analysis Design Practice"
type: "Design Practice"
author: "J. Smith"
reviewer: "A. Johnson"
approver: "M. Williams"
date: "2025-01-15"
status: "Approved"
---

# Introduction

Your document content here...

## Background

More content...

3. Run the server

export FOLIOS_PATH=/path/to/your/documents
folios

Or with uvx:

FOLIOS_PATH=/path/to/docs uvx folios

MCP Tools

Tool	Parameters	Description
get_document_content	document_id, version?	Retrieve document content (latest if version omitted)
get_document_metadata	document_id, version?	Get metadata including auto-parsed chapters
diff_document_versions	document_id, from_version, to_version	Diff between two versions
list_documents	status?, document_type?, author?	List documents with optional filters
list_document_versions	document_id	List all versions of a document

Document Schema

Metadata Fields

Field	Type	Description
id	int	Unique document identifier
version	int	Version number (sequential integers)
title	str	Document title
type	str	Document type
author	str	Document author
reviewer	str	Document reviewer
approver	str	Document approver
date	str	Date (ISO format recommended)
status	str	Document status
chapters	list	Auto-parsed from H1/H2 headings

Document Types

• Design Practice - Standard design methodology
• Guideline - Recommended approaches
• Best Practice - Industry best practices
• TRS - Technical Requirement Specification
• DVP - Design Verification Plan
• DVR - Detail Verification Review

Document Statuses

• Draft - Work in progress
• In Review - Under review
• Approved - Approved for use
• Withdrawn - No longer valid

Configuration

Environment Variable	Description	Default
FOLIOS_PATH	Path to documents folder	./documents

Example Usage with Claude Desktop

Add to your Claude Desktop MCP configuration:

{
  "mcpServers": {
    "folios": {
      "command": "uvx",
      "args": ["folios"],
      "env": {
        "FOLIOS_PATH": "/path/to/your/documents"
      }
    }
  }
}

Development

git clone https://github.com/alex-pradas/folios
cd folios
uv sync

# Run locally
FOLIOS_PATH=./examples/documents uv run folios

# Run tests
uv run pytest

License

MIT