Dokumen-Pintar

Dokumen-Pintar

Servidor MCP universal para CRUD de documentos em múltiplos formatos

Leia, escreva, pesquise e gerencie arquivos de texto, Office e PDF
a partir de qualquer agente de IA que suporte o Model Context Protocol.

Recursos  ·  Formatos  ·  Início Rápido  ·  Ferramentas  ·  Documentação  ·  Benchmark  ·  Contribuição

Baca dalam Bahasa Indonesia

Por que Dokumen-Pintar

A maioria dos servidores MCP de sistema de arquivos se limita a "leia este arquivo, escreva aquele arquivo." O Dokumen-Pintar trata documentos como dados estruturados que a IA pode navegar. Diga a um agente para atualizar um parágrafo por índice, definir uma célula por Sheet1!B2, percorrer uma árvore JSON com JSONPath, gerar um DOCX a partir de Markdown — tudo funciona da mesma forma em todos os formatos suportados.

Toda ferramenta de mutação tira um snapshot do arquivo primeiro. Toda ação é registrada em um log de auditoria. Todo caminho é isolado em raízes que você opta por incluir. A configuração padrão é sensata; os perfis cobrem o restante.

Recursos

Formatos Suportados

Início Rápido

1. Instalação

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. Crie uma Configuração

dokumen-pintar-init

Ou crie uma manualmente:

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

Todos os outros campos são opcionais com padrões sensatos. Veja docs/CONFIG.md.

3. Execute

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

Raízes ad-hoc sem arquivo de configuração

Substitua ou substitua as raízes de configuração pela linha de comando — útil para sessões pontuais ou 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

Verificação de integridade

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

Verifica a validade da configuração, existência das raízes, capacidade de escrita de snapshots .mcpdocs, handlers registrados e dependências opcionais de busca semântica.

4. Conecte a um 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 }
  }
}

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

Guia completo com receitas: docs/USAGE.md

Visão Geral das Ferramentas

62 ferramentas MCP organizadas por categoria:

_{* Somente registrado quando semantic_search.enabled = true e o extra [semantic] está instalado.}

Referência completa de parâmetros: docs/TOOLS.md

Arquitetura

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

Detalhes completos: docs/ARCHITECTURE.md

Testes

pip install -e ".[dev]"
pytest

Relatório de cobertura HTML: htmlcov/index.html

Números de desempenho e metodologia: docs/BENCHMARK.md

Documentação

Contribuição

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 são bem-vindos. Todos os testes devem passar e a cobertura deve permanecer em 100%. Leia AGENTS.md antes de enviar — cobre convenções, o protocolo de handlers e como adicionar um novo formato ou ferramenta.

Licença

MIT — 2026 firdausmntp

_{Construído por firdausmntp}