folios 0.4.0

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

Folios

A lightweight Model Context Protocol (MCP) server for giving agents the tools to query your local library of documents.

Documentation

What problem solves folios?

When working in engineering applications, AI agents often need access to a variety of internal documents such as design practices, guidelines, and specifications that are stored in a local, document-based knowledge management system. While Retreival Augmented Generation (RAG) implementation can provide such functionality, setting it up and maintaining it up to date can be complex and time-consuming. Why not accessing the documents directly? If the master information is stored in documents, Agentic AI is not going to change the quality processes that are already in place to manage knowledge in companies, so I believe in giving agents read-only access to the document library is a more straightforward approach. However, giving agent access to those system repositories con be challenging due to the restricted nature of their APIs or the lack of privileged access.

If you are developing agentic workflows, in order to mock the functionality to give agents the access to such complex management systems, Folios provides a simple MCP server that can be pointed to a folder of properly formatted Markdown files. This allows AI assistants to perform the same query behaviour with a very low setup cost from the user/developer side.

Features

• Zero Config - Just point to a folder of Markdown files and go
• Local First - Your documents stay on your machine or network, no cloud dependencies
• Flexible Metadata - Use any frontmatter fields your workflow needs
• Versioned Documents - Store multiple versions with simple {id}_v{version}.md naming

One-liner to install, run and configure

uvx folios --folios-path /path/to/your/documents

Quick guide to get started

1. Create your documents folder

Any normal local folder will do. 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

Frontmatter is flexible - include any fields your workflow requires:

---
author: "J. Smith"
date: "2025-01-15"
document_type: "Design Practice"
status: "Approved"
reviewer: "A. Johnson"
---

# Stress Analysis Design Practice

Lorem ipsum dolor sit amet, consectetur adipiscing elit.

## Background

More text here...

Only the --- delimiters and an H1 title are required. Missing fields show "NA" in responses.

3. Run the server

you can run folios directly with one terminal command

uvx folios --folios-path /path/to/your/documents

alternatively, you can add it to your LLM Client MCP configuration:

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

We have tested it with Claude Desktop and the GitHub Copilot Extension for VS Code, but it should work with any MCP-compatible client.

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

Core Metadata Fields

These fields are always present in metadata responses:

Field	Type	Description
id	int	Unique document identifier (from filename)
version	int	Version number (from filename)
title	str	Document title (from H1 heading)
author	str	Document author ("NA" if not in frontmatter)
date	str	Publication date ("NA" if not in frontmatter)
chapters	list	Auto-parsed from H2 headings

Dynamic Fields

Any additional frontmatter fields are included in metadata responses. Common examples:

• document_type - Document type (Design Practice, Guideline, etc.)
• status - Document status (Draft, Approved, etc.)
• reviewer, approver - Approval workflow fields
• Custom fields for your specific workflow

Configuration

Documents Path

Provide the documents folder path via CLI flag or environment variable:

Option	Description
--folios-path	Path to documents folder (CLI flag)
FOLIOS_PATH	Path to documents folder (environment variable)

Field Configuration (Optional)

Create a folios.toml in your documents folder to define allowed values for fields:

[fields.status]
values = ["Draft", "In Review", "Approved", "Withdrawn"]

[fields.document_type]
values = ["Design Practice", "Guideline", "Best Practice", "TRS"]

[fields.department]
values = ["Engineering", "Manufacturing", "HR"]

This helps agents understand what values are valid for each field.

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

This project is licensed under the terms of the MIT license.