mcp-okf 0.1.0__tar.gz

mcp_okf-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.pyc
+.venv/
+.pytest_cache/
+.superpowers/
+dist/
+.DS_Store
+uv.lock

mcp_okf-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Daniel Xavier Araújo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mcp_okf-0.1.0/PKG-INFO

@@ -0,0 +1,68 @@
+Metadata-Version: 2.5
+Name: mcp-okf
+Version: 0.1.0
+Summary: MCP server de base de conhecimento sobre bundles OKF (alm-sync): indexação, enriquecimento e busca semântica
+Author-email: Daniel Xavier Araújo <danielxaraujo@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: markdown-it-py>=3
+Requires-Dist: mcp[cli]>=2.2
+Requires-Dist: pyyaml>=6
+Requires-Dist: qdrant-client[fastembed]>=1.12
+Description-Content-Type: text/markdown
+
+# mcp-okf
+
+Servidor MCP que transforma um bundle OKF (pasta com `index.md` e um `.md` por documento, como o gerado pela
+alm-sync do [mcp-alm](https://github.com/dxaraujo/mcp-alm)) numa base de conhecimento consultável em linguagem natural.
+
+- **Índice vetorial:** Qdrant em modo local (pasta no disco, sem servidor), busca híbrida denso + BM25 com fusão RRF.
+- **Embeddings:** fastembed local, `paraphrase-multilingual-mpnet-base-v2` (PT-BR); nada sai da máquina.
+- **Enriquecimento:** feito pela própria LLM do cliente (sem chave de API): resumo, palavras-chave/sinônimos,
+  entidades e perguntas que o documento responde.
+- **Links:** `links` do frontmatter (nomes do DOORS Next), links do corpo para outros arquivos do bundle (`cita`) e
+  URL do ALM de artefato que está no bundle; backlinks e documentos semanticamente similares na leitura.
+
+## Instalação
+
+```bash
+uv sync
+# baixa os modelos uma vez (~1 GB), para a 1ª indexação não estourar o timeout do cliente MCP
+uv run python -c "from mcp_okf import store; store.embed_dense(['x']); store.embed_sparse(['x'])"
+claude mcp add okf -- uv --directory /caminho/mcp-okf run mcp-okf
+```
+
+Dados em `~/.config/mcp-okf/` (`%APPDATA%\mcp-okf` no Windows; ou `MCP_OKF_HOME`): `qdrant/` e
+`state/<sha1(root)>.json` (hash, links e enriquecimento de cada documento). Nada é gravado no bundle.
+O Qdrant local trava a pasta: só um processo do mcp-okf por vez.
+
+## Tools
+
+`root` é sempre o caminho absoluto do bundle.
+
+| Tool | Parâmetros | Devolve |
+|---|---|---|
+| `okf_index` | `root`, `limit=200`, `force=False` | `{documentos, indexados, removidos, restantes, a_enriquecer}`; incremental por sha256; chame até `restantes=0` |
+| `okf_enrich_next` | `root`, `limit=5` | `{restantes, instrucoes, documentos: [{path, id, type, title, description, body, links}]}` |
+| `okf_save_enrichment` | `root`, `items: [{path, summary, keywords, entities, questions}]` | `{gravados, restantes}` |
+| `okf_search` | `root`, `query`, `limit=8`, `folder?`, `type?` | `[{path, id, title, type, folder, score, summary, trechos: [{section, text}]}]` |
+| `okf_list_documents` | `root`, `folder?`, `type?` | `[{path, id, title, type, folder, description, indexado, enriquecido}]` |
+| `okf_get_document` | `root`, `ref` (path ou id) | `{path, markdown, enrichment, links: {saida, entrada, similares}}` |
+
+Fluxo: `okf_index` até `restantes=0` → `okf_enrich_next` / `okf_save_enrichment` até `restantes=0` → perguntas
+com `okf_search` e `okf_get_document`. Depois de um novo sincronismo da alm-sync, rode `okf_index` de novo: só o que
+mudou é reindexado, e só o que mudou volta para a fila de enriquecimento.
+
+## Como indexa
+
+Cada documento vira pontos `chunk` (corpo dividido por heading `#`..`###`, seções longas por parágrafo; cada chunk
+leva o prefixo `<tipo> <id> — <título> | <pasta> | <seção>`) e um ponto `doc` (cabeçalho + enriquecimento). A busca
+funde o ranking denso e o BM25 (RRF) e agrupa por documento.
+
+## Testes
+
+```bash
+uv run pytest
+```
+Os testes usam Qdrant em memória e embeddings falsos (não baixam modelo).

mcp_okf-0.1.0/README.md

@@ -0,0 +1,54 @@
+# mcp-okf
+
+Servidor MCP que transforma um bundle OKF (pasta com `index.md` e um `.md` por documento, como o gerado pela
+alm-sync do [mcp-alm](https://github.com/dxaraujo/mcp-alm)) numa base de conhecimento consultável em linguagem natural.
+
+- **Índice vetorial:** Qdrant em modo local (pasta no disco, sem servidor), busca híbrida denso + BM25 com fusão RRF.
+- **Embeddings:** fastembed local, `paraphrase-multilingual-mpnet-base-v2` (PT-BR); nada sai da máquina.
+- **Enriquecimento:** feito pela própria LLM do cliente (sem chave de API): resumo, palavras-chave/sinônimos,
+  entidades e perguntas que o documento responde.
+- **Links:** `links` do frontmatter (nomes do DOORS Next), links do corpo para outros arquivos do bundle (`cita`) e
+  URL do ALM de artefato que está no bundle; backlinks e documentos semanticamente similares na leitura.
+
+## Instalação
+
+```bash
+uv sync
+# baixa os modelos uma vez (~1 GB), para a 1ª indexação não estourar o timeout do cliente MCP
+uv run python -c "from mcp_okf import store; store.embed_dense(['x']); store.embed_sparse(['x'])"
+claude mcp add okf -- uv --directory /caminho/mcp-okf run mcp-okf
+```
+
+Dados em `~/.config/mcp-okf/` (`%APPDATA%\mcp-okf` no Windows; ou `MCP_OKF_HOME`): `qdrant/` e
+`state/<sha1(root)>.json` (hash, links e enriquecimento de cada documento). Nada é gravado no bundle.
+O Qdrant local trava a pasta: só um processo do mcp-okf por vez.
+
+## Tools
+
+`root` é sempre o caminho absoluto do bundle.
+
+| Tool | Parâmetros | Devolve |
+|---|---|---|
+| `okf_index` | `root`, `limit=200`, `force=False` | `{documentos, indexados, removidos, restantes, a_enriquecer}`; incremental por sha256; chame até `restantes=0` |
+| `okf_enrich_next` | `root`, `limit=5` | `{restantes, instrucoes, documentos: [{path, id, type, title, description, body, links}]}` |
+| `okf_save_enrichment` | `root`, `items: [{path, summary, keywords, entities, questions}]` | `{gravados, restantes}` |
+| `okf_search` | `root`, `query`, `limit=8`, `folder?`, `type?` | `[{path, id, title, type, folder, score, summary, trechos: [{section, text}]}]` |
+| `okf_list_documents` | `root`, `folder?`, `type?` | `[{path, id, title, type, folder, description, indexado, enriquecido}]` |
+| `okf_get_document` | `root`, `ref` (path ou id) | `{path, markdown, enrichment, links: {saida, entrada, similares}}` |
+
+Fluxo: `okf_index` até `restantes=0` → `okf_enrich_next` / `okf_save_enrichment` até `restantes=0` → perguntas
+com `okf_search` e `okf_get_document`. Depois de um novo sincronismo da alm-sync, rode `okf_index` de novo: só o que
+mudou é reindexado, e só o que mudou volta para a fila de enriquecimento.
+
+## Como indexa
+
+Cada documento vira pontos `chunk` (corpo dividido por heading `#`..`###`, seções longas por parágrafo; cada chunk
+leva o prefixo `<tipo> <id> — <título> | <pasta> | <seção>`) e um ponto `doc` (cabeçalho + enriquecimento). A busca
+funde o ranking denso e o BM25 (RRF) e agrupa por documento.
+
+## Testes
+
+```bash
+uv run pytest
+```
+Os testes usam Qdrant em memória e embeddings falsos (não baixam modelo).

mcp_okf-0.1.0/mcp_okf/bundle.py

@@ -0,0 +1,150 @@
+"""Leitura de um bundle OKF (alm-sync do mcp-alm): documentos, frontmatter, links entre eles e chunks.
+Só disco e texto; o índice fica em store.py."""
+from __future__ import annotations
+
+import hashlib
+import os
+import posixpath
+import re
+from pathlib import Path
+from urllib.parse import unquote
+
+import yaml
+from markdown_it import MarkdownIt
+
+SKIP = {"index.md", "sync.md"}  # arquivos do próprio bundle, não documentos
+CHUNK_MAX = 1500
+_HEADING = re.compile(r"^(#{1,3})\s+(.+?)\s*#*\s*$", re.M)
+_LEADING_ID = re.compile(r"(\d+)(?:[ _:-].*)?")
+_LINK_ID = re.compile(r"\s*(\d+)\s*:")  # item de `links`: 'id: título'
+_MD = MarkdownIt()
+
+
+def root(dest: str) -> str:
+    """Raiz do bundle: `dest` tem de ser absoluto (o cwd do MCP não é o bundle)."""
+    if not os.path.isabs(dest):
+        raise ValueError(f"root precisa ser caminho absoluto: {dest}")
+    path = os.path.realpath(dest)
+    if not os.path.isdir(path):
+        raise ValueError(f"pasta não encontrada: {dest}")
+    return path
+
+
+def read_document(text: str) -> tuple[dict, str]:
+    """(frontmatter YAML completo, corpo). Sem cabeçalho ou YAML inválido: ({}, texto)."""
+    if not text.startswith("---\n") or (end := text.find("\n---\n", 3)) < 0:
+        return {}, text
+    try:
+        head = yaml.safe_load(text[4:end]) or {}
+    except yaml.YAMLError:
+        return {}, text
+    return (head, text[end + 5:]) if isinstance(head, dict) else ({}, text)
+
+
+def _text(value) -> str | None:
+    return " ".join(str(value).split()) if value not in (None, "") else None
+
+
+def load(root_dir: str, path: str) -> dict:
+    """Documento pelo caminho relativo (posix) ao root."""
+    full = os.path.join(root_dir, *path.split("/"))
+    with open(full, "rb") as f:
+        raw = f.read()
+    head, body = read_document(raw.decode("utf-8"))
+    name = posixpath.basename(path)[:-3]
+    m = _LEADING_ID.fullmatch(name)
+    doc_id = head.get("id") if head.get("id") is not None else (m.group(1) if m else None)
+    sources = head.get("sources") if isinstance(head.get("sources"), list) else []
+    tags = head.get("tags") if isinstance(head.get("tags"), list) else []
+    return {"path": path, "id": str(doc_id) if doc_id is not None else None,
+            "title": _text(head.get("title")) or name, "type": _text(head.get("type")),
+            "folder": path.split("/")[0] if "/" in path else "", "description": _text(head.get("description")),
+            "tags": [str(t) for t in tags], "resource": _text(head.get("resource")),
+            "last_modified": next((str(s["last_modified"]) for s in sources
+                                   if isinstance(s, dict) and s.get("last_modified")), None),
+            "head": head, "body": body, "hash": hashlib.sha256(raw).hexdigest()}
+
+
+def scan(root_dir: str) -> dict[str, dict]:
+    """Todos os .md do bundle (menos index.md/sync.md na raiz), por caminho relativo posix."""
+    docs = {}
+    for full in sorted(Path(root_dir).rglob("*.md")):
+        rel = full.relative_to(root_dir).as_posix()
+        if rel in SKIP or any(part.startswith(".") for part in full.relative_to(root_dir).parts):
+            continue
+        docs[rel] = load(root_dir, rel)
+    return docs
+
+
+def _targets(markdown: str) -> list[str]:
+    """Alvos de link do corpo (markdown-it, inclusive '<alvo com espaço>')."""
+    out = []
+    for token in _MD.parse(markdown):
+        for child in token.children or []:
+            if child.type == "link_open" and (href := child.attrGet("href")):
+                out.append(str(href))
+    return out
+
+
+def resolve(doc_path: str, target: str, by_id: dict[str, str], docs: dict) -> str | None:
+    """Alvo de link -> caminho de documento do bundle; None se estiver fora dele."""
+    target = unquote(target).split("#")[0].strip()
+    if not target:
+        return None
+    if "/rm/resources/" in target:  # URL do ALM: só liga se o artefato estiver no bundle
+        return next((p for p, d in docs.items() if d["resource"] == target.split("?")[0]), None)
+    if re.match(r"[a-z][a-z0-9+.-]*:", target, re.I):
+        return None
+    base = "" if target.startswith("/") else posixpath.dirname(doc_path)
+    path = posixpath.normpath(posixpath.join(base, target.lstrip("/")))
+    if path.startswith("..") or path.startswith("/"):
+        return None  # fora do bundle
+    if path in docs:
+        return path
+    m = _LEADING_ID.fullmatch(posixpath.basename(path).removesuffix(".md"))
+    return by_id.get(m.group(1)) if m else None
+
+
+def links(doc: dict, docs: dict, by_id: dict[str, str]) -> list[dict]:
+    """[{rel, path}] sem repetição: do frontmatter `links {rel: ['id: título']}` e do corpo (rel 'cita')."""
+    out: dict[tuple[str, str], dict] = {}
+    raw = doc["head"].get("links")
+    for rel, items in (raw.items() if isinstance(raw, dict) else []):
+        for item in items if isinstance(items, list) else [items]:
+            m = _LINK_ID.match(str(item))
+            if m and (path := by_id.get(m.group(1))) and path != doc["path"]:
+                out[(str(rel), path)] = {"rel": str(rel), "path": path}
+    for target in _targets(doc["body"]):
+        if (path := resolve(doc["path"], target, by_id, docs)) and path != doc["path"]:
+            out.setdefault(("cita", path), {"rel": "cita", "path": path})
+    return list(out.values())
+
+
+def by_id(docs: dict) -> dict[str, str]:
+    return {d["id"]: p for p, d in docs.items() if d["id"]}
+
+
+def _split(text: str) -> list[str]:
+    """Quebra por parágrafo em pedaços de até CHUNK_MAX (parágrafo maior que isso vai inteiro)."""
+    parts, cur = [], ""
+    for para in re.split(r"\n\s*\n", text):
+        if cur and len(cur) + len(para) > CHUNK_MAX:
+            parts.append(cur)
+            cur = ""
+        cur = f"{cur}\n\n{para}" if cur else para
+    return parts + ([cur] if cur.strip() else [])
+
+
+def chunks(doc: dict) -> list[dict]:
+    """[{section, text}] por heading (#..###); `text` já com o prefixo de contexto para o embedding."""
+    body, sections = doc["body"], []
+    marks = list(_HEADING.finditer(body))
+    starts = [(0, "")] + [(m.start(), m.group(2)) for m in marks]
+    for i, (start, title) in enumerate(starts):
+        end = marks[i].start() if i < len(marks) else len(body)
+        text = body[start:end].strip()
+        if text:
+            sections += [(title, part.strip()) for part in _split(text) if part.strip()]
+    prefix = " ".join(filter(None, [doc["type"], doc["id"], "—", doc["title"]]))
+    return [{"section": s, "text": f"{prefix} | {doc['folder']} | {s}\n{t}"} for s, t in sections] or \
+        [{"section": "", "text": f"{prefix} | {doc['folder']}\n{doc['description'] or doc['title']}"}]

mcp_okf-0.1.0/mcp_okf/server.py

@@ -0,0 +1,52 @@
+"""Servidor MCP de base de conhecimento sobre bundles OKF (alm-sync do mcp-alm).
+
+As tools ficam em tools.py, registradas com `@tool`; leitura do bundle em bundle.py e índice em store.py.
+"""
+from __future__ import annotations
+
+import functools
+
+from mcp.server.mcpserver import MCPServer
+from mcp.server.mcpserver.exceptions import ToolError
+
+mcp = MCPServer(
+    "okf",
+    instructions=(
+        "Base de conhecimento sobre um bundle OKF (pasta com index.md e um .md por documento, como o gerado pela "
+        "alm-sync). `root` é sempre o caminho absoluto da pasta. Preparar: okf_index até restantes=0; depois "
+        "okf_enrich_next -> gere o enriquecimento de cada documento -> okf_save_enrichment, até restantes=0. "
+        "Consultar: okf_search (pergunta em linguagem natural), okf_get_document (documento inteiro + links de "
+        "saída, de entrada e similares), okf_list_documents (inventário). A busca funciona sem enriquecimento, mas "
+        "fica melhor com ele. Cite os documentos pelo path/id."
+    ),
+)
+
+# RuntimeError: Qdrant travado por outro processo; OSError: disco; ValueError/LookupError: parâmetro inválido
+EXPECTED = (RuntimeError, OSError, LookupError, ValueError)
+
+
+def tool(fn):
+    """Registra `fn` como tool e devolve `fn` intacta (testes veem as exceções originais).
+
+    O MCP SDK 2.x esconde o texto de exceções que não são ToolError."""
+    @functools.wraps(fn)
+    def wrapper(*args, **kwargs):
+        try:
+            return fn(*args, **kwargs)
+        except EXPECTED as exc:
+            raise ToolError(str(exc)) from exc
+
+    mcp.tool()(wrapper)
+    return fn
+
+
+# importado depois de `tool` existir: o módulo registra as tools ao ser carregado
+from . import tools  # noqa: E402,F401
+
+
+def main() -> None:
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()

mcp_okf-0.1.0/mcp_okf/store.py

@@ -0,0 +1,190 @@
+"""Índice do bundle: Qdrant local (vetor denso + BM25, fusão RRF) e o estado por bundle (hash, links, enriquecimento).
+
+Estado em <home>/state/<sha1(root)>.json: {path: {hash, indexed_hash, links: [{rel, path}], enrichment}}.
+É o que torna a indexação incremental e mantém o enriquecimento entre reindexações. Nada é gravado no bundle."""
+from __future__ import annotations
+
+import functools
+import hashlib
+import json
+import os
+import sys
+import threading
+import uuid
+from datetime import datetime, timezone
+from pathlib import Path
+
+from qdrant_client import QdrantClient, models
+
+from . import bundle
+
+COLLECTION = "okf"
+DENSE_MODEL = "sentence-transformers/paraphrase-multilingual-mpnet-base-v2"
+DENSE_DIM = 768
+SPARSE_MODEL = "Qdrant/bm25"
+_NS = uuid.UUID("5b0f0c6e-2a51-4f43-9d55-0c2c7f1e9a10")
+# um lock para tudo: tools síncronas podem rodar em threads e o estado é um JSON
+LOCK = threading.RLock()
+
+
+def home() -> Path:
+    if env := os.environ.get("MCP_OKF_HOME"):
+        return Path(env)
+    if sys.platform == "win32":
+        return Path(os.environ["APPDATA"]) / "mcp-okf"
+    return Path.home() / ".config" / "mcp-okf"
+
+
+@functools.cache
+def client() -> QdrantClient:
+    """Qdrant em modo local (a pasta fica travada para um processo só)."""
+    path = home() / "qdrant"
+    path.mkdir(parents=True, exist_ok=True)
+    try:
+        qc = QdrantClient(path=str(path))
+    except RuntimeError as exc:
+        raise RuntimeError(f"Índice em {path} já está aberto por outro processo do mcp-okf: {exc}") from exc
+    _ensure(qc)
+    return qc
+
+
+def _ensure(qc: QdrantClient) -> None:
+    if qc.collection_exists(COLLECTION):
+        return
+    qc.create_collection(
+        COLLECTION,
+        vectors_config={"dense": models.VectorParams(size=DENSE_DIM, distance=models.Distance.COSINE)},
+        sparse_vectors_config={"bm25": models.SparseVectorParams(modifier=models.Modifier.IDF)})
+    # shortcut: sem índices de payload (o Qdrant local os ignora); criar em bundle/path/folder/type/kind ao migrar
+    # para servidor Qdrant
+
+
+@functools.cache
+def _dense():
+    from fastembed import TextEmbedding
+    return TextEmbedding(DENSE_MODEL)
+
+
+@functools.cache
+def _sparse():
+    from fastembed import SparseTextEmbedding
+    return SparseTextEmbedding(SPARSE_MODEL, language="portuguese")
+
+
+def embed_dense(texts: list[str]) -> list[list[float]]:
+    return [v.tolist() for v in _dense().embed(texts)]
+
+
+def embed_sparse(texts: list[str], query: bool = False) -> list[models.SparseVector]:
+    fn = _sparse().query_embed if query else _sparse().embed
+    return [models.SparseVector(indices=e.indices.tolist(), values=e.values.tolist()) for e in fn(texts)]
+
+
+# --- estado
+
+def _state_file(root: str) -> Path:
+    return home() / "state" / f"{hashlib.sha1(root.encode()).hexdigest()}.json"
+
+
+def load_state(root: str) -> dict:
+    try:
+        return json.loads(_state_file(root).read_text(encoding="utf-8"))
+    except FileNotFoundError:
+        return {}
+
+
+def save_state(root: str, state: dict) -> None:
+    path = _state_file(root)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp = path.with_suffix(".tmp")
+    tmp.write_text(json.dumps(state, ensure_ascii=False, indent=1), encoding="utf-8")
+    os.replace(tmp, path)  # atômico: estado nunca fica pela metade
+
+
+def enriched(entry: dict) -> bool:
+    return entry.get("enrichment", {}).get("hash") == entry.get("hash")
+
+
+def indexed(entry: dict) -> bool:
+    return entry.get("indexed_hash") == entry.get("hash")
+
+
+# --- pontos
+
+def _pid(root: str, path: str, n) -> str:
+    return str(uuid.uuid5(_NS, f"{root}\n{path}\n{n}"))
+
+
+def _filter(root: str, **eq) -> models.Filter:
+    return models.Filter(must=[models.FieldCondition(key=k, match=models.MatchValue(value=v))
+                               for k, v in {"bundle": root, **eq}.items() if v is not None])
+
+
+def _payload(root: str, doc: dict, kind: str, section: str = "", text: str = "") -> dict:
+    return {"bundle": root, "path": doc["path"], "id": doc["id"], "title": doc["title"], "type": doc["type"],
+            "folder": doc["folder"], "kind": kind, "section": section, "text": text}
+
+
+def doc_text(doc: dict, enrichment: dict | None) -> str:
+    """Texto do ponto 'doc': cabeçalho + enriquecimento (é ele que casa pergunta em linguagem natural com jargão)."""
+    e = enrichment or {}
+    parts = [" ".join(filter(None, [doc["type"], doc["id"], "—", doc["title"]])), doc["folder"],
+             doc["description"], e.get("summary"), ", ".join(e.get("keywords", [])),
+             ", ".join(e.get("entities", [])), "\n".join(e.get("questions", []))]
+    return "\n".join(p for p in parts if p)
+
+
+def _doc_point(root: str, doc: dict, enrichment: dict | None) -> models.PointStruct:
+    text = doc_text(doc, enrichment)
+    return models.PointStruct(id=_pid(root, doc["path"], "doc"),
+                               vector={"dense": embed_dense([text])[0], "bm25": embed_sparse([text])[0]},
+                               payload=_payload(root, doc, "doc", text=(enrichment or {}).get("summary") or ""))
+
+
+def _delete(root: str, path: str) -> None:
+    client().delete(COLLECTION, points_selector=models.FilterSelector(filter=_filter(root, path=path)))
+
+
+def write_doc(root: str, doc: dict, enrichment: dict | None) -> None:
+    """Apaga os pontos do documento e grava os chunks + o ponto 'doc'."""
+    parts = bundle.chunks(doc)
+    texts = [c["text"] for c in parts]
+    dense, sparse = embed_dense(texts), embed_sparse(texts)
+    points = [models.PointStruct(id=_pid(root, doc["path"], n), vector={"dense": d, "bm25": s},
+                                 payload=_payload(root, doc, "chunk", c["section"], c["text"].split("\n", 1)[-1]))
+              for n, (c, d, s) in enumerate(zip(parts, dense, sparse))]
+    _delete(root, doc["path"])
+    client().upsert(COLLECTION, points + [_doc_point(root, doc, enrichment)])
+
+
+def write_doc_point(root: str, doc: dict, enrichment: dict | None) -> None:
+    client().upsert(COLLECTION, [_doc_point(root, doc, enrichment)])
+
+
+def delete_doc(root: str, path: str) -> None:
+    _delete(root, path)
+
+
+def search(root: str, query: str, limit: int, folder: str | None, type_: str | None) -> list[models.ScoredPoint]:
+    flt = _filter(root, folder=folder, type=type_)
+    wide = limit * 5
+    return client().query_points(
+        COLLECTION,
+        prefetch=[models.Prefetch(query=embed_dense([query])[0], using="dense", filter=flt, limit=wide),
+                  models.Prefetch(query=embed_sparse([query], query=True)[0], using="bm25", filter=flt, limit=wide)],
+        query=models.FusionQuery(fusion=models.Fusion.RRF), limit=wide, with_payload=True).points
+
+
+def similar(root: str, path: str, limit: int) -> list[models.ScoredPoint]:
+    """Documentos mais próximos pelo vetor do ponto 'doc' (vazio se o documento não estiver indexado)."""
+    found = client().retrieve(COLLECTION, [_pid(root, path, "doc")], with_vectors=["dense"])
+    if not found:
+        return []
+    flt = _filter(root, kind="doc")
+    flt.must_not = [models.FieldCondition(key="path", match=models.MatchValue(value=path))]
+    return client().query_points(COLLECTION, query=found[0].vector["dense"], using="dense", query_filter=flt,
+                                 limit=limit, with_payload=True).points
+
+
+def now() -> str:
+    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")

mcp_okf-0.1.0/mcp_okf/tools.py

@@ -0,0 +1,185 @@
+"""Tools do mcp-okf: indexação, enriquecimento (feito pela LLM do cliente), busca e leitura."""
+from __future__ import annotations
+
+from typing import TypedDict
+
+from . import bundle, store
+from .server import tool
+
+BODY_MAX = 12000  # corpo devolvido para enriquecer: limita o contexto gasto por documento
+SNIPPET_MAX = 800
+LIST_MAX, ITEM_MAX, SUMMARY_MAX = 30, 300, 2000
+INSTRUCOES = (
+    "Para cada documento, gere em PT-BR e chame okf_save_enrichment com items=[{path, summary, keywords, entities, "
+    "questions}]: summary = 2-3 frases do que o documento define; keywords = termos de negócio e sinônimos que uma "
+    "pessoa usaria para procurá-lo (inclusive os que o texto não usa literalmente); entities = atores, sistemas, "
+    "regras e dados citados; questions = 3-5 perguntas que o documento responde. Use só o que está no documento e "
+    "nos links; não invente.")
+
+
+class Enrichment(TypedDict):
+    path: str
+    summary: str
+    keywords: list[str]
+    entities: list[str]
+    questions: list[str]
+
+
+def _ref(entry: dict, path: str) -> dict:
+    return {"path": path, "id": entry.get("id"), "title": entry.get("title")}
+
+
+def _pending_enrichment(state: dict) -> list[str]:
+    return [p for p, e in state.items() if store.indexed(e) and not store.enriched(e)]
+
+
+@tool
+def okf_index(root: str, limit: int = 200, force: bool = False) -> dict:
+    """Indexa o bundle OKF em `root` (caminho absoluto): lê todos os .md, recalcula os links entre documentos, remove
+    do índice os arquivos apagados e (re)indexa até `limit` documentos novos ou alterados (sha256 diferente).
+    Chame até `restantes` = 0. `force=True` (só na 1ª chamada) reindexa tudo, mantendo o enriquecimento.
+    Devolve {documentos, indexados, removidos, restantes, a_enriquecer}."""
+    with store.LOCK:
+        rd = bundle.root(root)
+        docs = bundle.scan(rd)
+        ids = bundle.by_id(docs)
+        state = store.load_state(rd)
+        removed = [p for p in state if p not in docs]
+        for p in removed:
+            store.delete_doc(rd, p)
+            del state[p]
+        for p, d in docs.items():
+            e = state.setdefault(p, {})
+            e.update(hash=d["hash"], id=d["id"], title=d["title"], type=d["type"], folder=d["folder"],
+                     links=bundle.links(d, docs, ids))
+            if force:
+                e.pop("indexed_hash", None)
+        pending = [p for p in docs if not store.indexed(state[p])]
+        done = 0
+        try:
+            for p in pending[:limit]:
+                store.write_doc(rd, docs[p], state[p].get("enrichment"))  # enriquecimento antigo vale até o novo
+                state[p]["indexed_hash"] = docs[p]["hash"]
+                done += 1
+        finally:
+            store.save_state(rd, state)  # progresso salvo mesmo se um documento falhar
+        return {"documentos": len(docs), "indexados": done, "removidos": len(removed),
+                "restantes": len(pending) - done, "a_enriquecer": len(_pending_enrichment(state))}
+
+
+@tool
+def okf_enrich_next(root: str, limit: int = 5) -> dict:
+    """Próximos documentos indexados sem enriquecimento (ou alterados depois dele), para a LLM enriquecer e gravar
+    com okf_save_enrichment. Devolve {restantes, instrucoes, documentos: [{path, id, type, title, body, links}]}."""
+    with store.LOCK:
+        rd = bundle.root(root)
+        state = store.load_state(rd)
+        pending = _pending_enrichment(state)
+        out = []
+        for p in pending[:max(1, limit)]:
+            doc = bundle.load(rd, p)
+            out.append({"path": p, "id": doc["id"], "type": doc["type"], "title": doc["title"],
+                        "description": doc["description"], "body": doc["body"][:BODY_MAX],
+                        "links": [{"rel": l["rel"], **_ref(state.get(l["path"], {}), l["path"])}
+                                  for l in state[p].get("links", [])]})
+        return {"restantes": len(pending), "instrucoes": INSTRUCOES, "documentos": out}
+
+
+def _strings(item: dict, key: str) -> list[str]:
+    value = item.get(key) or []
+    if not isinstance(value, list) or not all(isinstance(x, str) for x in value):
+        raise ValueError(f"{item.get('path')}: {key} deve ser lista de textos")
+    return [" ".join(x.split())[:ITEM_MAX] for x in value if x.strip()][:LIST_MAX]
+
+
+@tool
+def okf_save_enrichment(root: str, items: list[Enrichment]) -> dict:
+    """Grava o enriquecimento gerado para os documentos de okf_enrich_next e reindexa o ponto de resumo de cada um.
+    items = [{path, summary, keywords[], entities[], questions[]}]. Devolve {gravados, restantes}."""
+    with store.LOCK:
+        rd = bundle.root(root)
+        state = store.load_state(rd)
+        valid = []
+        for item in items:  # valida tudo antes de gravar qualquer coisa
+            if not isinstance(item, dict) or item.get("path") not in state:
+                path = item.get("path") if isinstance(item, dict) else item
+                raise ValueError(f"path fora do índice (rode okf_index): {path}")
+            summary = item.get("summary")
+            if not isinstance(summary, str) or not summary.strip():
+                raise ValueError(f"{item['path']}: summary obrigatório")
+            valid.append((item["path"], {"summary": " ".join(summary.split())[:SUMMARY_MAX],
+                                         **{k: _strings(item, k) for k in ("keywords", "entities", "questions")}}))
+        for path, enrichment in valid:
+            doc = bundle.load(rd, path)
+            entry = state[path]
+            entry["enrichment"] = {**enrichment, "hash": doc["hash"], "at": store.now()}
+            if store.indexed(entry) and entry["hash"] == doc["hash"]:
+                store.write_doc_point(rd, doc, entry["enrichment"])
+        store.save_state(rd, state)
+        return {"gravados": len(valid), "restantes": len(_pending_enrichment(state))}
+
+
+@tool
+def okf_search(root: str, query: str, limit: int = 8, folder: str | None = None, type: str | None = None) -> list:
+    """Busca semântica + palavra-chave (híbrida) no bundle indexado, em linguagem natural. Filtros opcionais: `folder`
+    (primeira pasta do path) e `type` (tipo do frontmatter). Devolve até `limit` documentos, do mais relevante:
+    [{path, id, title, type, folder, score, summary, trechos: [{section, text}]}]. Leia o documento inteiro com
+    okf_get_document quando o trecho não bastar."""
+    if not query.strip():
+        raise ValueError("query vazia")
+    with store.LOCK:
+        rd = bundle.root(root)
+        state = store.load_state(rd)
+        out: dict[str, dict] = {}
+        for hit in store.search(rd, query, max(1, limit), folder, type):
+            p = hit.payload
+            r = out.get(p["path"])
+            if r is None:
+                if len(out) >= limit:
+                    continue
+                r = out[p["path"]] = {
+                    "path": p["path"], "id": p["id"], "title": p["title"], "type": p["type"], "folder": p["folder"],
+                    "score": round(hit.score, 4),
+                    "summary": state.get(p["path"], {}).get("enrichment", {}).get("summary"), "trechos": []}
+            if p["kind"] == "chunk" and len(r["trechos"]) < 2:
+                r["trechos"].append({"section": p["section"], "text": p["text"][:SNIPPET_MAX]})
+        return list(out.values())
+
+
+@tool
+def okf_list_documents(root: str, folder: str | None = None, type: str | None = None) -> list:
+    """Inventário do bundle (sem corpo): [{path, id, title, type, folder, description, indexado, enriquecido}]."""
+    with store.LOCK:
+        rd = bundle.root(root)
+        state = store.load_state(rd)
+        out = []
+        for p, d in bundle.scan(rd).items():
+            if (folder and d["folder"] != folder) or (type and d["type"] != type):
+                continue
+            e = {**state.get(p, {}), "hash": d["hash"]}  # compara com o arquivo de agora
+            out.append({"path": p, "id": d["id"], "title": d["title"], "type": d["type"], "folder": d["folder"],
+                        "description": d["description"], "indexado": store.indexed(e),
+                        "enriquecido": store.enriched(e)})
+        return out
+
+
+@tool
+def okf_get_document(root: str, ref: str) -> dict:
+    """Documento por path (relativo ao root) ou id: {path, markdown (arquivo inteiro), enrichment, links: {saida,
+    entrada, similares}}. saida/entrada = [{rel, path, id, title}] (rel = nome do link no DOORS Next ou 'cita' para
+    link no texto); similares = documentos mais próximos semanticamente [{path, id, title, score}]."""
+    with store.LOCK:
+        rd = bundle.root(root)
+        state = store.load_state(rd)
+        path = ref if ref in state else next((p for p, e in state.items() if e.get("id") == str(ref)), None)
+        if path is None:
+            raise LookupError(f"documento não encontrado no índice: {ref} (rode okf_index)")
+        with open(f"{rd}/{path}", encoding="utf-8") as f:
+            markdown = f.read()
+        entry = state[path]
+        return {"path": path, "markdown": markdown, "enrichment": entry.get("enrichment"), "links": {
+            "saida": [{"rel": l["rel"], **_ref(state.get(l["path"], {}), l["path"])} for l in entry.get("links", [])],
+            "entrada": [{"rel": l["rel"], **_ref(e, p)} for p, e in state.items()
+                        for l in e.get("links", []) if l["path"] == path],
+            "similares": [{"path": h.payload["path"], "id": h.payload["id"], "title": h.payload["title"],
+                           "score": round(h.score, 4)} for h in store.similar(rd, path, 5)]}}

mcp_okf-0.1.0/pyproject.toml

@@ -0,0 +1,29 @@
+[project]
+name = "mcp-okf"
+version = "0.1.0"
+description = "MCP server de base de conhecimento sobre bundles OKF (alm-sync): indexação, enriquecimento e busca semântica"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Daniel Xavier Araújo", email = "danielxaraujo@gmail.com" }]
+requires-python = ">=3.10"
+dependencies = [
+    "mcp[cli]>=2.2",
+    "qdrant-client[fastembed]>=1.12",
+    "pyyaml>=6",
+    "markdown-it-py>=3",
+]
+
+[project.scripts]
+mcp-okf = "mcp_okf.server:main"
+
+[dependency-groups]
+dev = ["pytest>=8"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["."]

mcp_okf-0.1.0/tests/conftest.py

@@ -0,0 +1,60 @@
+"""Bundle de exemplo copiado para tmp, Qdrant em memória e embeddings falsos (sem baixar modelo)."""
+import re
+import zlib
+
+import pytest
+from qdrant_client import QdrantClient, models
+
+from mcp_okf import store
+
+# bundle OKF no formato da alm-sync: {caminho relativo: conteúdo}
+BUNDLE = {
+    '01-Requisitos/10-login-do-cliente.md': '---\ntype: Requisito\ntitle: Login do cliente\ndescription: "Acesso ao portal com CPF e senha."\nresource: "https://alm.example.com/rm/resources/TX_10"\ntags:\n  - "01-Requisitos"\nsources:\n  - id: doors-next\n    resource: "https://alm.example.com/rm/resources/TX_10"\n    last_modified: "2026-01-10T13:05:00Z"\nid: 10\n---\nO cliente acessa o portal informando CPF e senha. O CPF é validado conforme [2001 RN - Validar CPF do cliente](../03-Regras/2001-rn-validar-cpf-do-cliente.md).\n',
+    '03-Casos de Uso/2010-uc-cadastrar-cliente.md': '---\ntype: Caso de Uso\ntitle: UC - Cadastrar cliente\nresource: "https://alm.example.com/rm/resources/TX_2010"\ntags:\n  - "03-Casos de Uso"\nsources:\n  - id: doors-next\n    resource: "https://alm.example.com/rm/resources/TX_2010"\n    author: "human:ana.souza"\n    last_modified: "2026-01-10T13:05:00Z"\ngenerated:\n  by: "process:alm-mcp/1.0.14"\n  at: "2026-01-11T19:20:00Z"\nid: 2010\nlinks:\n  Vincular A:\n    - "10: Login do cliente"\n    - "9999: Fora do bundle"\n---\n## Fluxo Básico\n\n1. O usuário informa os dados do cliente.\n2. O sistema valida o documento: [2001 RN - Validar CPF do cliente](https://alm.example.com/rm/resources/TX_2001)\n3. Ver também [manual](https://example.com/manual.pdf) e [fora](../../segredo.md).\n',
+    '03-Regras/2001-rn-validar-cpf-do-cliente.md': '---\ntype: Regra de Negócio\ntitle: RN - Validar CPF do cliente\nresource: "https://alm.example.com/rm/resources/TX_2001"\ntags:\n  - "03-Regras"\nid: 2001\n---\n## Regra\n\nO CPF deve ter 11 dígitos e dígitos verificadores válidos (módulo 11). CPFs com todos os dígitos iguais são rejeitados.\n\n## Mensagem\n\nExibir "CPF inválido" e bloquear o envio do formulário.\n',
+    'index.md': '---\nokf_version: "0.2"\n---\n\n# 01-Requisitos\n\n* [10 — Login do cliente](</01-Requisitos/10-login-do-cliente.md>) - Acesso ao portal com CPF e senha.\n\n# 03-Casos de Uso\n\n* [2010 — UC - Cadastrar cliente](</03-Casos de Uso/2010-uc-cadastrar-cliente.md>)\n\n# 03-Regras\n\n* [2001 — RN - Validar CPF do cliente](</03-Regras/2001-rn-validar-cpf-do-cliente.md>)\n\n# Bundle\n\n* [Sincronismo ALM → OKF](/sync.md) - Situação de cada artefato do DOORS Next baixado neste bundle.\n',
+    'sync.md': '---\ntype: Relatório de Sincronismo\ntitle: Sincronismo ALM → OKF\n---\n| Artefato | Pasta | Última atualização ALM | Hash | Status |\n|---|---|---|---|---|\n',
+}
+
+
+def _words(text: str) -> list[str]:
+    return re.findall(r"\w+", text.lower())
+
+
+def fake_dense(texts):
+    out = []
+    for t in texts:
+        v = [0.0] * store.DENSE_DIM
+        for w in _words(t):
+            v[zlib.crc32(w.encode()) % store.DENSE_DIM] += 1.0
+        out.append(v if any(v) else [1.0] + [0.0] * (store.DENSE_DIM - 1))
+    return out
+
+
+def fake_sparse(texts, query=False):
+    out = []
+    for t in texts:
+        idx = sorted({zlib.crc32(w.encode()) % 100_000 for w in _words(t)})
+        out.append(models.SparseVector(indices=idx, values=[1.0] * len(idx)))
+    return out
+
+
+@pytest.fixture
+def root(tmp_path):
+    dest = tmp_path / "bundle"
+    for rel, text in BUNDLE.items():
+        (dest / rel).parent.mkdir(parents=True, exist_ok=True)
+        (dest / rel).write_text(text, encoding="utf-8")
+    return str(dest)
+
+
+@pytest.fixture
+def okf(tmp_path, monkeypatch):
+    monkeypatch.setenv("MCP_OKF_HOME", str(tmp_path / "home"))
+    qc = QdrantClient(":memory:")
+    store._ensure(qc)
+    monkeypatch.setattr(store, "client", lambda: qc)
+    monkeypatch.setattr(store, "embed_dense", fake_dense)
+    monkeypatch.setattr(store, "embed_sparse", fake_sparse)
+    from mcp_okf import tools
+    return tools

mcp_okf-0.1.0/tests/test_bundle.py

@@ -0,0 +1,57 @@
+import os
+
+import pytest
+
+from mcp_okf import bundle
+
+UC = "03-Casos de Uso/2010-uc-cadastrar-cliente.md"
+RN = "03-Regras/2001-rn-validar-cpf-do-cliente.md"
+LOGIN = "01-Requisitos/10-login-do-cliente.md"
+
+
+def test_root_requires_absolute_existing_dir(root):
+    with pytest.raises(ValueError):
+        bundle.root("relativo/bundle")
+    with pytest.raises(ValueError):
+        bundle.root(os.path.join(root, "nao-existe"))
+
+
+def test_scan_reads_nested_frontmatter_and_skips_bundle_files(root):
+    docs = bundle.scan(root)
+    assert set(docs) == {UC, RN, LOGIN}
+    uc = docs[UC]
+    assert (uc["id"], uc["type"], uc["folder"]) == ("2010", "Caso de Uso", "03-Casos de Uso")
+    assert uc["head"]["links"] == {"Vincular A": ["10: Login do cliente", "9999: Fora do bundle"]}
+    assert uc["last_modified"] == "2026-01-10T13:05:00Z"
+
+
+def test_id_falls_back_to_file_name(root):
+    with open(os.path.join(root, "01-Requisitos", "77-sem-cabecalho.md"), "w") as f:
+        f.write("Texto sem frontmatter.\n")
+    doc = bundle.load(root, "01-Requisitos/77-sem-cabecalho.md")
+    assert (doc["id"], doc["title"], doc["head"]) == ("77", "77-sem-cabecalho", {})
+
+
+def test_links_from_frontmatter_body_and_alm_url(root):
+    docs = bundle.scan(root)
+    ids = bundle.by_id(docs)
+    assert bundle.links(docs[UC], docs, ids) == [{"rel": "Vincular A", "path": LOGIN}, {"rel": "cita", "path": RN}]
+    assert bundle.links(docs[LOGIN], docs, ids) == [{"rel": "cita", "path": RN}]  # relativo '../03-Regras/...'
+
+
+def test_resolve_ignores_targets_outside_bundle(root):
+    docs = bundle.scan(root)
+    assert bundle.resolve(UC, "../../segredo.md", {}, docs) is None
+    assert bundle.resolve(UC, "https://example.com/x.md", {}, docs) is None
+
+
+def test_chunks_by_heading_with_context_prefix(root):
+    parts = bundle.chunks(bundle.scan(root)[RN])
+    assert [c["section"] for c in parts] == ["Regra", "Mensagem"]
+    assert parts[0]["text"].startswith("Regra de Negócio 2001 — RN - Validar CPF do cliente | 03-Regras | Regra\n")
+
+
+def test_long_section_is_split_by_paragraph():
+    body = "\n\n".join("p" * 900 for _ in range(3))
+    doc = {"body": body, "type": None, "id": None, "title": "T", "folder": "", "description": None}
+    assert len(bundle.chunks(doc)) == 3

mcp_okf-0.1.0/tests/test_tools.py

@@ -0,0 +1,72 @@
+import os
+
+import pytest
+
+UC = "03-Casos de Uso/2010-uc-cadastrar-cliente.md"
+RN = "03-Regras/2001-rn-validar-cpf-do-cliente.md"
+LOGIN = "01-Requisitos/10-login-do-cliente.md"
+
+
+def test_index_is_incremental(okf, root):
+    assert okf.okf_index(root, limit=2) == {"documentos": 3, "indexados": 2, "removidos": 0, "restantes": 1,
+                                            "a_enriquecer": 2}
+    assert okf.okf_index(root)["indexados"] == 1
+    assert okf.okf_index(root)["indexados"] == 0
+    with open(os.path.join(root, RN), "a") as f:
+        f.write("\nNovo parágrafo.\n")
+    assert okf.okf_index(root)["indexados"] == 1
+    os.remove(os.path.join(root, LOGIN))
+    assert okf.okf_index(root)["removidos"] == 1
+    assert {d["path"] for d in okf.okf_list_documents(root)} == {UC, RN}
+    assert all(r["path"] != LOGIN for r in okf.okf_search(root, "login portal senha"))
+    assert okf.okf_index(root, force=True)["indexados"] == 2
+
+
+def test_enrichment_round_trip(okf, root):
+    okf.okf_index(root)
+    batch = okf.okf_enrich_next(root, limit=1)
+    assert batch["restantes"] == 3 and len(batch["documentos"]) == 1 and "summary" in batch["instrucoes"]
+    uc = okf.okf_enrich_next(root, limit=5)["documentos"]
+    assert {"rel": "Vincular A", "path": LOGIN, "id": "10", "title": "Login do cliente"} in \
+        next(d for d in uc if d["path"] == UC)["links"]
+    items = [{"path": d["path"], "summary": f"Resumo {d['title']}", "keywords": ["onboarding"], "entities": [],
+              "questions": []} for d in uc]
+    assert okf.okf_save_enrichment(root, items) == {"gravados": 3, "restantes": 0}
+    assert okf.okf_enrich_next(root)["documentos"] == []
+    assert okf.okf_index(root)["a_enriquecer"] == 0
+    # keyword que só existe no enriquecimento já acha o documento
+    assert okf.okf_search(root, "onboarding", limit=3)[0]["summary"].startswith("Resumo")
+    with open(os.path.join(root, RN), "a") as f:
+        f.write("\nMudou.\n")
+    assert okf.okf_index(root)["a_enriquecer"] == 1
+
+
+def test_save_enrichment_validates_before_writing(okf, root):
+    okf.okf_index(root)
+    ok = {"path": RN, "summary": "x", "keywords": [], "entities": [], "questions": []}
+    with pytest.raises(ValueError):
+        okf.okf_save_enrichment(root, [ok, {**ok, "path": "../fora.md"}])
+    with pytest.raises(ValueError):
+        okf.okf_save_enrichment(root, [{**ok, "keywords": "não é lista"}])
+    assert okf.okf_enrich_next(root)["restantes"] == 3
+
+
+def test_search_and_filters(okf, root):
+    okf.okf_index(root)
+    hits = okf.okf_search(root, "CPF dígitos verificadores módulo 11")
+    assert hits[0]["path"] == RN and hits[0]["trechos"][0]["section"] == "Regra"
+    assert {h["folder"] for h in okf.okf_search(root, "CPF", folder="01-Requisitos")} == {"01-Requisitos"}
+    assert okf.okf_search(root, "CPF", type="Caso de Uso")[0]["path"] == UC
+
+
+def test_get_document_links_backlinks_and_similar(okf, root):
+    okf.okf_index(root)
+    doc = okf.okf_get_document(root, "2001")
+    assert doc["path"] == RN and doc["markdown"].startswith("---\ntype: Regra de Negócio")
+    assert {(l["rel"], l["path"]) for l in doc["links"]["entrada"]} == {("cita", UC), ("cita", LOGIN)}
+    assert doc["links"]["saida"] == []
+    assert RN not in {s["path"] for s in doc["links"]["similares"]} and doc["links"]["similares"]
+    assert okf.okf_get_document(root, UC)["links"]["saida"][0] == {
+        "rel": "Vincular A", "path": LOGIN, "id": "10", "title": "Login do cliente"}
+    with pytest.raises(LookupError):
+        okf.okf_get_document(root, "../../etc/passwd")