Dokumen-Pintar

Dokumen-Pintar

Servidor MCP universal para CRUD de documentos en múltiples formatos

Lee, escribe, busca y gestiona archivos de texto, Office y PDF
desde cualquier agente de IA que soporte el Protocolo de Contexto de Modelo.

Características  ·  Formatos  ·  Inicio rápido  ·  Herramientas  ·  Documentación  ·  Benchmark  ·  Contribuciones

Baca dalam Bahasa Indonesia

Por qué Dokumen-Pintar

La mayoría de los servidores MCP de sistema de archivos se limitan a "lee este archivo, escribe ese archivo". Dokumen-Pintar trata los documentos como datos estructurados que la IA puede navegar. Dile a un agente que actualice un párrafo por índice, que establezca una celda por Sheet1!B2, que recorra un árbol JSON con JSONPath, que genere un DOCX desde Markdown: funciona igual en todos los formatos compatibles.

Cada herramienta de mutación crea una instantánea del archivo primero. Cada acción queda registrada en un registro de auditoría. Cada ruta está aislada en raíces que tú aceptas. La configuración predeterminada es sensata; los perfiles cubren el resto.

Características

Formatos compatibles

Inicio rápido

1. Instalación

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. Crea una configuración

dokumen-pintar-init

O crea una manualmente:

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

Todos los demás campos son opcionales con valores predeterminados sensatos. Consulta docs/CONFIG.md.

3. Ejecuta

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

Raíces ad-hoc sin archivo de configuración

Anula o reemplaza las raíces de configuración desde la línea de comandos: útil para sesiones puntuales o scripts:

# 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

Verificación de estado

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

Verifica la validez de la configuración, la existencia de las raíces, la capacidad de escritura de instantáneas .mcpdocs, los manejadores registrados y las dependencias opcionales de búsqueda semántica.

4. Conéctate a un cliente de IA

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

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

Ejemplos de uso

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

Guía completa con recetas: docs/USAGE.md

Resumen de herramientas

62 herramientas MCP organizadas por categoría:

_{* Solo se registra cuando semantic_search.enabled = true y el extra [semantic] está instalado.}

Referencia completa de parámetros: docs/TOOLS.md

Arquitectura

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)"]

Detalles completos: docs/ARCHITECTURE.md

Pruebas

pip install -e ".[dev]"
pytest

Informe de cobertura HTML: htmlcov/index.html

Números de rendimiento y metodología: docs/BENCHMARK.md

Documentación

Contribuciones

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

Las PR son bienvenidas. Todas las pruebas deben pasar y la cobertura debe mantenerse al 100%. Lee AGENTS.md antes de enviar: cubre convenciones, el protocolo de manejadores y cómo añadir un nuevo formato o herramienta.

Licencia

MIT — 2026 firdausmntp

_{Construido por firdausmntp}