argus-mcp-cli 0.1.0__tar.gz

argus_mcp_cli-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+node_modules/
+dist/
+.venv/
+__pycache__/
+*.pyc
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+packages/cli/tests/__tmp_*

argus_mcp_cli-0.1.0/PKG-INFO

@@ -0,0 +1,6 @@
+Metadata-Version: 2.5
+Name: argus-mcp-cli
+Version: 0.1.0
+Summary: Argus MCP server — ferramentas de engenharia para agentes de IA
+Requires-Python: >=3.12
+Requires-Dist: mcp>=1.0

argus_mcp_cli-0.1.0/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "argus-mcp-cli"
+version = "0.1.0"
+description = "Argus MCP server — ferramentas de engenharia para agentes de IA"
+requires-python = ">=3.12"
+dependencies = [
+    "mcp>=1.0",
+]
+
+[project.scripts]
+argus-mcp = "argus_mcp.server:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/argus_mcp"]
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.24",
+    "ruff>=0.5",
+    "mypy>=1.10",
+]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 88
+target-version = "py312"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP"]
+ignore = ["E501"]
+
+[tool.mypy]
+strict = true

argus_mcp_cli-0.1.0/src/argus_mcp/config.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class Config:
+    project_root: Path
+    vault_path: Path
+    stack: str
+
+
+def load() -> Config:
+    if root := os.getenv("ARGUS_PROJECT_ROOT"):
+        project_root = Path(root)
+    else:
+        project_root = _find_project_root()
+
+    if vault := os.getenv("ARGUS_VAULT_PATH"):
+        vault_path = Path(vault)
+    else:
+        vault_path = project_root / "vault"
+
+    return Config(
+        project_root=project_root,
+        vault_path=vault_path,
+        stack=_read_stack(project_root),
+    )
+
+
+def _find_project_root() -> Path:
+    for directory in [Path.cwd(), *Path.cwd().parents]:
+        if (directory / ".argus").exists() or (directory / "CLAUDE.md").exists():
+            return directory
+    raise RuntimeError("project root não encontrado — rode argus init primeiro")
+
+
+def _read_stack(root: Path) -> str:
+    config_file = root / ".argus" / "config.json"
+    if config_file.exists():
+        data = json.loads(config_file.read_text(encoding="utf-8"))
+        return str(data.get("stack", "unknown"))
+    return "unknown"

argus_mcp_cli-0.1.0/src/argus_mcp/server.py

@@ -0,0 +1,52 @@
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Callable, Coroutine
+from typing import Any
+
+import mcp.types as types
+from mcp.server import Server
+from mcp.server.stdio import stdio_server
+
+from argus_mcp.tools import context, memory, scaffold, validate
+
+server = Server("argus")
+
+_tools: list[types.Tool] = [
+    *context.TOOLS,
+    *memory.TOOLS,
+    *scaffold.TOOLS,
+    *validate.TOOLS,
+]
+
+Handler = Callable[[dict[str, Any]], Coroutine[Any, Any, str]]
+
+_handlers: dict[str, Handler] = {
+    **context.HANDLERS,
+    **memory.HANDLERS,
+    **scaffold.HANDLERS,
+    **validate.HANDLERS,
+}
+
+
+@server.list_tools()  # type: ignore[attr-defined, untyped-decorator]
+async def list_tools() -> list[types.Tool]:
+    return _tools
+
+
+@server.call_tool()  # type: ignore[attr-defined, untyped-decorator]
+async def call_tool(name: str, arguments: dict[str, Any]) -> list[types.TextContent]:
+    handler = _handlers.get(name)
+    if handler is None:
+        text = f"[ERRO] tool desconhecida: {name}"
+    else:
+        text = await handler(arguments or {})
+    return [types.TextContent(type="text", text=text)]
+
+
+def main() -> None:
+    async def _run() -> None:
+        async with stdio_server() as (read, write):
+            await server.run(read, write, server.create_initialization_options())
+
+    asyncio.run(_run())

argus_mcp_cli-0.1.0/src/argus_mcp/tools/context.py

@@ -0,0 +1,124 @@
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import Any
+
+import mcp.types as types
+
+from argus_mcp.config import load
+
+TOOLS: list[types.Tool] = [
+    types.Tool(
+        name="read_project_context",
+        description="Retorna contexto consolidado do projeto (stack, backlog em andamento, últimas decisões, instruções do agente).",
+        input_schema={"type": "object", "properties": {}},
+    ),
+    types.Tool(
+        name="read_spec",
+        description="Lê um arquivo de spec do vault por ID ou path.",
+        input_schema={
+            "type": "object",
+            "properties": {
+                "id": {"type": "string", "description": "ID do item (ex: ARGUS-015)"},
+                "path": {"type": "string", "description": "Path relativo ao vault"},
+            },
+        },
+    ),
+]
+
+
+async def _read_project_context(args: dict[str, object]) -> str:
+    try:
+        cfg = load()
+    except RuntimeError as e:
+        return f"[ERRO] {e}"
+
+    parts: list[str] = ["# Contexto do projeto"]
+
+    parts.append(f"\n## Stack\n{cfg.stack}")
+
+    backlog_file = cfg.vault_path / "03-specifications" / "backlog.md"
+    if backlog_file.exists():
+        in_progress = _extract_in_progress(backlog_file.read_text(encoding="utf-8"))
+        parts.append(f"\n## Backlog (em andamento)\n{in_progress}")
+
+    decision_file = cfg.vault_path / "00-project-charter" / "decision-log.md"
+    if decision_file.exists():
+        decisions = _extract_last_decisions(
+            decision_file.read_text(encoding="utf-8"), n=5
+        )
+        parts.append(f"\n## Últimas decisões\n{decisions}")
+
+    instrucao_file = cfg.vault_path / "11-ai-context" / "instrucao-ia.md"
+    if instrucao_file.exists():
+        parts.append(
+            f"\n## Instruções do agente\n{instrucao_file.read_text(encoding='utf-8')}"
+        )
+
+    return "\n".join(parts)
+
+
+async def _read_spec(args: dict[str, object]) -> str:
+    spec_id = args.get("id")
+    spec_path = args.get("path")
+
+    if not spec_id and not spec_path:
+        return "[ERRO] forneça id ou path"
+
+    try:
+        cfg = load()
+    except RuntimeError as e:
+        return f"[ERRO] {e}"
+
+    target: Path | None
+    if spec_path:
+        target = cfg.vault_path / str(spec_path)
+    else:
+        target = _find_by_id(cfg.vault_path, str(spec_id))
+
+    if target is None or not target.exists():
+        return f"[ERRO] spec não encontrada: {spec_id or spec_path}"
+
+    return target.read_text(encoding="utf-8")
+
+
+def _extract_in_progress(backlog: str) -> str:
+    match = re.search(r"## Em andamento\n(.*?)(?=\n---|\Z)", backlog, re.DOTALL)
+    if not match:
+        return "nenhum item em andamento"
+    block = match.group(1).strip()
+    rows = [
+        row
+        for row in block.splitlines()
+        if row.startswith("|") and "---" not in row and "ID" not in row
+    ]
+    return "\n".join(rows) if rows else "nenhum item em andamento"
+
+
+def _extract_last_decisions(log: str, n: int) -> str:
+    entries = re.split(r"\n(?=## \[)", log)
+    decision_entries = [e.strip() for e in entries if e.strip().startswith("## [")]
+    last = decision_entries[-n:] if len(decision_entries) >= n else decision_entries
+    return "\n\n".join(last)
+
+
+def _find_by_id(vault: Path, spec_id: str) -> Path | None:
+    for md in vault.rglob("*.md"):
+        if spec_id.lower() in md.stem.lower():
+            return md
+        try:
+            if (
+                spec_id.lower()
+                in md.read_text(encoding="utf-8", errors="ignore").lower()[:200]
+            ):
+                return md
+        except OSError:
+            continue
+    return None
+
+
+HANDLERS: dict[str, Any] = {
+    "read_project_context": _read_project_context,
+    "read_spec": _read_spec,
+}

argus_mcp_cli-0.1.0/src/argus_mcp/tools/memory.py

@@ -0,0 +1,165 @@
+from __future__ import annotations
+
+import re
+from datetime import date
+from typing import Any
+
+import mcp.types as types
+
+from argus_mcp.config import load
+
+TOOLS: list[types.Tool] = [
+    types.Tool(
+        name="save_decision",
+        description="Acrescenta uma entrada formatada no decision-log.md do vault.",
+        input_schema={
+            "type": "object",
+            "properties": {
+                "title": {"type": "string"},
+                "context": {"type": "string"},
+                "decision": {"type": "string"},
+                "reason": {"type": "string"},
+                "discarded": {"type": "string"},
+            },
+            "required": ["title", "context", "decision", "reason"],
+        },
+    ),
+    types.Tool(
+        name="update_backlog",
+        description="Move um item do backlog (start | complete | block).",
+        input_schema={
+            "type": "object",
+            "properties": {
+                "id": {"type": "string"},
+                "action": {"type": "string", "enum": ["start", "complete", "block"]},
+                "note": {"type": "string"},
+            },
+            "required": ["id", "action"],
+        },
+    ),
+]
+
+
+async def _save_decision(args: dict[str, object]) -> str:
+    try:
+        cfg = load()
+    except RuntimeError as e:
+        return f"[ERRO] {e}"
+
+    decision_file = cfg.vault_path / "00-project-charter" / "decision-log.md"
+    if not decision_file.exists():
+        return f"[ERRO] decision-log.md não encontrado em {decision_file}"
+
+    today = date.today().isoformat()
+    title = args.get("title", "")
+    entry_lines = [
+        f"\n## [{today}] {title}",
+        f"\n**Contexto:** {args.get('context', '')}",
+        f"**Decisão:** {args.get('decision', '')}",
+        f"**Motivo:** {args.get('reason', '')}",
+    ]
+    if discarded := args.get("discarded"):
+        entry_lines.append(f"**Alternativas descartadas:** {discarded}")
+
+    entry = "\n".join(entry_lines)
+    current = decision_file.read_text(encoding="utf-8")
+    decision_file.write_text(current.rstrip() + "\n" + entry + "\n", encoding="utf-8")
+
+    return f"Decisão salva: {title}"
+
+
+async def _update_backlog(args: dict[str, object]) -> str:
+    try:
+        cfg = load()
+    except RuntimeError as e:
+        return f"[ERRO] {e}"
+
+    backlog_file = cfg.vault_path / "03-specifications" / "backlog.md"
+    if not backlog_file.exists():
+        return f"[ERRO] backlog.md não encontrado em {backlog_file}"
+
+    item_id = str(args.get("id", ""))
+    action = str(args.get("action", ""))
+    note = str(args.get("note", ""))
+
+    if action not in ("start", "complete", "block"):
+        return f"[ERRO] action inválida: {action}"
+
+    content = backlog_file.read_text(encoding="utf-8")
+
+    if action == "start":
+        content = _move_to_in_progress(content, item_id)
+    elif action == "complete":
+        content = _move_to_complete(content, item_id)
+    elif action == "block":
+        content = _add_block_note(content, item_id, note)
+
+    if content is None:
+        return f"[ERRO] item não encontrado: {item_id}"
+
+    backlog_file.write_text(content, encoding="utf-8")
+    return f"Backlog atualizado: {item_id} → {action}"
+
+
+def _find_item_row(content: str, item_id: str) -> re.Match[str] | None:
+    pattern = rf"(\| {re.escape(item_id)} \|[^\n]+)"
+    return re.search(pattern, content)
+
+
+def _move_to_in_progress(content: str, item_id: str) -> str:
+    match = _find_item_row(content, item_id)
+    if not match:
+        return content
+
+    row = match.group(1)
+    content = content.replace(row, "", 1)
+
+    in_progress_header = (
+        "## Em andamento\n\n| ID | Item | Responsável |\n|----|------|-------------|"
+    )
+    insert_row = f"| {item_id} | {_extract_item_text(row)} | — |"
+    return content.replace(
+        in_progress_header,
+        f"{in_progress_header}\n{insert_row}",
+        1,
+    )
+
+
+def _move_to_complete(content: str, item_id: str) -> str:
+    match = _find_item_row(content, item_id)
+    if not match:
+        return content
+
+    row = match.group(1)
+    item_text = _extract_item_text(row)
+    today = date.today().isoformat()
+    content = content.replace(row, "", 1)
+
+    complete_row = f"| ~~{item_id}~~ | ~~{item_text}~~ | {today} |"
+    concluido_marker = "## Concluído\n\n| ID | Item | Data |\n|----|------|------|"
+    return content.replace(
+        concluido_marker,
+        f"{concluido_marker}\n{complete_row}",
+        1,
+    )
+
+
+def _add_block_note(content: str, item_id: str, note: str) -> str:
+    match = _find_item_row(content, item_id)
+    if not match:
+        return content
+
+    row = match.group(1)
+    suffix = f" ⚠️ {note}" if note else " ⚠️ bloqueado"
+    return content.replace(row, row.rstrip() + suffix, 1)
+
+
+def _extract_item_text(row: str) -> str:
+    parts = [p.strip() for p in row.split("|") if p.strip()]
+    return parts[1] if len(parts) > 1 else row
+
+
+HANDLERS: dict[str, Any] = {
+    "save_decision": _save_decision,
+    "update_backlog": _update_backlog,
+}