Dokumen-Pintar

Universal MCP server for cross-format document CRUD

Read, write, search, and manage text, Office, and PDF files
from any AI agent that supports the Model Context Protocol.

Features  ·  Formats  ·  Quick Start  ·  Tools  ·  Docs  ·  Benchmark  ·  Contributing

Baca dalam Bahasa Indonesia

Why Dokumen-Pintar

Most filesystem MCP servers stop at "read this file, write that file." Dokumen-Pintar treats documents as structured data the AI can navigate. Tell an agent to update a paragraph by index, set a cell by Sheet1!B2, walk a JSON tree with JSONPath, generate a DOCX from Markdown - it works the same way across every supported format.

Every mutating tool snapshots the file first. Every action lands in an audit log. Every path is sandboxed to roots you opt in. The default config is sensible; the profiles cover the rest.

Features

Supported Formats

Quick Start

1. Install

pip install dokumen-pintar

git clone https://github.com/firdausmntp/Dokumen-Pintar.git
cd Dokumen-Pintar
pip install -e ".[dev]"

pip install dokumen-pintar[semantic]

2. Create a Config

dokumen-pintar-init

Or create one manually:

{
  "roots": [
    { "name": "documents", "path": "~/Documents", "writable": true },
    { "name": "projects",  "path": "~/Projects",  "writable": true }
  ]
}

All other fields are optional with sensible defaults. See docs/CONFIG.md.

3. Run

dokumen-pintar --config dokumen-pintar.config.json

Ad-hoc roots without a config file

Override or replace config roots from the command line — handy for one-off sessions or scripting:

# Single writable root, no config file required
dokumen-pintar --root docs:/path/to/folder

# Multiple roots, mix read-only and writable, choose stdio transport
dokumen-pintar \
  --root project:/repo:rw \
  --root refs:/library:ro \
  --transport stdio

# Force every root to read-only (overrides config + --root)
dokumen-pintar --config myconfig.json --read-only

# Path-only shorthand (root name derived from basename)
dokumen-pintar --root /home/me/Documents

Health check

dokumen-pintar-doctor --config dokumen-pintar.config.json

Verifies config validity, root existence, .mcpdocs snapshot writability, registered handlers, and optional semantic-search dependencies.

4. Connect to an AI Client

{
  "mcpServers": {
    "dokumen-pintar": {
      "command": "dokumen-pintar",
      "args": ["--config", "/path/to/dokumen-pintar.config.json"]
    }
  }
}

{
  "transport": {
    "stdio": false,
    "http": { "enabled": true, "port": 7878 }
  }
}

Usage Examples

# List available workspace roots
workspace_list_roots()

# Read a Word document
content_read(path="documents:/reports/q1.docx")

# Create a new file
file_create(path="documents:/notes/todo.txt", content="Hello World")

# Find & replace inside a file
content_replace(path="documents:/notes/todo.txt", old="World", new="Everyone")

# Full-text search across all PDFs
search_content(query="budget 2024", format="pdf")

# Read an Excel cell
structured_get(path="documents:/data.xlsx", expr="cell:Sheet1!B2")

# Update a JSON key
structured_set(path="documents:/config.json", expr="$.database.port", value=5432)

# Delete an XML node
structured_delete(path="documents:/data.xml", expr="//item[@id='old']")

# Batch rename (dry-run first)
batch_rename(glob="*.txt", pattern="draft_", replacement="final_", dry_run=true)

# Undo last change
version_undo(path="documents:/reports/q1.docx")

Full guide with recipes: docs/USAGE.md

Tools Overview

62 MCP tools organized by category:

_{* Only registered when semantic_search.enabled = true and the [semantic] extra is installed.}

Full parameter reference: docs/TOOLS.md

Architecture

flowchart TD
    Client["AI Client\n(Claude, Cursor, VS Code, ...)"]
    Client -->|"MCP protocol\n(stdio or HTTP/SSE)"| Server

    subgraph Server["dokumen-pintar server"]
        PG["PathGuard\nsandboxed multi-root"]
        H["Handlers\n9 format parsers"]
        V["Versions\ncopy-on-write snapshots"]
        A["AuditLog\nJSONL mutation log"]
        S["Search\nfilename + content"]
        SE["Semantic\nvector index (optional)"]
    end

    Server --> FS["Filesystem\n(sandboxed workspace roots)"]

Full details: docs/ARCHITECTURE.md

Testing

pip install -e ".[dev]"
pytest

HTML coverage report: htmlcov/index.html

Performance numbers and methodology: docs/BENCHMARK.md

Documentation

Contributing

git clone https://github.com/firdausmntp/Dokumen-Pintar.git
cd Dokumen-Pintar
pip install -e ".[dev]"

ruff check src/             # lint
mypy src/dokumen_pintar/    # type check
pytest                      # test + coverage

PRs welcome. All tests must pass and coverage must stay at 100%. Read AGENTS.md before submitting - it covers conventions, the handler protocol, and how to add a new format or tool.

License

MIT — 2026 firdausmntp

_{Built by firdausmntp}