Lograft

Raft together logs, code, and tickets into post-mortem-ready investigation reports.

lograft is an MCP server that turns raw log query results into structured incident reports — Markdown (paste-into-ticket), JSON (machine-readable), and self-contained HTML (share offline). It composes Microsoft's official @azure/mcp for live Azure Monitor queries, and contributes the parts MS does NOT solve: KQL parsing, log↔git↔ticket correlation, PII redaction, multi-format reporting.

Works in any MCP-compatible client: opencode, Cursor, Claude Desktop, VS Code GitHub Copilot, Windsurf, Zed, Continue.dev.

• Status: beta (0.1.x)
• License: MIT
• Runtime: Node 20.10+

---

Quick start

npx lograft

That's it. The MCP server starts on stdio and waits for a client to call its tools.

To use lograft as a daily tool, install globally:

npm i -g lograft@beta
lograft   # starts MCP server on stdio

For live Azure mode, you also need @azure/mcp (auto-spawned via npx if absent, but installing it globally is faster):

npm i -g @azure/mcp@^2
az login   # azmcp handles all Azure auth

---

What it does

Given Azure log query results (live or pasted) plus a git repo, lograft produces a single investigation bundle:

reports/<UTC-timestamp>/
├── report.md     # Jira-paste-ready summary + correlations
├── data.json     # machine-readable findings
└── report.html   # offline-viewable, self-contained, CSP-locked

Correlation joins are explicit-keys only: operation_Id, your configured ticket regex (e.g. [A-Z]+-\d+), and a service allowlist. Timestamp proximity is a tiebreaker, never a primary signal (no noise explosion).

Default-on PII redaction — emails, JWTs, GUIDs in auth context, Authorization headers, IPv4/IPv6, RFC1918 private ranges, internal hostnames (*.internal, *.corp, *.local). The redactor is internal middleware — there is no "skip redaction" tool surface.

---

MCP client setup

lograft speaks the MCP stdio transport. Below are the snippets for the four distinct config formats. Tested in opencode, Cursor, Claude Desktop; the other clients use one of these same formats — contributions welcome to confirm.

opencode (opencode.json or ~/.config/opencode/config.json)

{
  "mcp": {
    "servers": {
      "lograft": {
        "command": "npx",
        "args": ["-y", "lograft@beta"]
      }
    }
  }
}

Claude Desktop family (claude_desktop_config.json / Cursor mcp.json / Windsurf / Zed)

{
  "mcpServers": {
    "lograft": {
      "command": "npx",
      "args": ["-y", "lograft@beta"]
    }
  }
}

Paths:

• Claude Desktop (macOS): ~/Library/Application Support/Claude/claude_desktop_config.json
• Claude Desktop (Windows): %APPDATA%\Claude\claude_desktop_config.json
• Cursor: ~/.cursor/mcp.json (global) or .cursor/mcp.json (project)
• Windsurf: ~/.codeium/windsurf/mcp_config.json
• Zed: similar shape — see Zed docs

VS Code GitHub Copilot (settings.json)

{
  "chat.mcp.servers": {
    "lograft": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "lograft@beta"]
    }
  }
}

Continue.dev (~/.continue/config.json)

{
  "experimental": {
    "modelContextProtocolServers": [
      {
        "transport": {
          "type": "stdio",
          "command": "npx",
          "args": ["-y", "lograft@beta"]
        }
      }
    ]
  }
}

---

Tools

lograft exposes 5 fine-grained MCP tools plus 1 convenience orchestrator. Most users want lograft_investigate first. The atomic tools exist for partial pipelines.

Tool	Purpose
lograft_investigate	Full pipeline: parse → normalize → repo context → correlate → redact → render bundle. The tool most users want.
lograft_parse_kql	Pure: extract tables, time range, ticket mentions, projections from a KQL query.
lograft_normalize	Pure: turn CSV / JSON / azure-monitor-json into a unified 5-field rowset.
lograft_gather_repo_context	Shells out to git log for the last N days of commits.
lograft_correlate	The heart: joins rows ↔ commits ↔ tickets ↔ atoms via explicit keys only.
lograft_render_report	Writes md+json+html bundle. Redactor middleware runs on input — non-bypassable.

The redactor is NOT a public tool by design (plan D13). If it were optional via tool selection, a misbehaving LLM client could exfiltrate raw PII into a Jira paste. Bypassing requires explicit redaction.bypass: true on the render call and emits a prominent stderr warning.

---

Example — paste mode

You already have a Portal export CSV and want a report.

// Client calls lograft_investigate with:
{
  "result": {
    "kind": "inline",
    "format": "csv",
    "data": "timestamp,message,operation_Id,cloud_RoleName\n2026-05-22T13:58:00Z,InvalidSignature MYPROJ-42,op-1,PaymentService\n…"
  },
  "kql": {
    "kind": "inline",
    "text": "exceptions | where timestamp > ago(1h) | project timestamp, message, operation_Id"
  },
  "repoPath": "/path/to/your/repo",
  "outDir": "./reports"
}

Output:

reports/20260522-141023/
├── report.md
├── data.json
└── report.html

report.md opens with a ≤500-char headline summary block suitable for pasting into a ticket.

---

Example — live mode (delegates to azmcp)

{
  "kql": {
    "kind": "inline",
    "text": "AppExceptions | where TimeGenerated > ago(1h) | project TimeGenerated, Message, operation_Id"
  },
  "live": {
    "workspaceId": "<log-analytics-workspace-id>",
    "subscriptionId": "<subscription-id>",
    "table": "AppExceptions",
    "hours": 1
  },
  "repoPath": "/path/to/your/repo"
}

Under the hood lograft shells out to:

azmcp monitor workspace log query \
  --subscription <subscription-id> \
  --workspace <workspace-id> \
  --table AppExceptions \
  --query "AppExceptions | where ... " \
  --output json \
  --hours 1

All Azure credentials are handled by azmcp via Microsoft's DefaultAzureCredential chain — lograft never touches AZURE_* env vars itself. See Authentication docs.

If azmcp is missing, lograft returns a clear error with install instructions.

---

Configuration

Place an optional lograft.config.toml in your project root (or ~/.config/lograft/lograft.config.toml). Resolution order:

1. --configPath arg on lograft_investigate (explicit)
2. <MCP-process-cwd>/lograft.config.toml
3. ~/.config/lograft/lograft.config.toml
4. Built-in defaults

See examples/lograft.generic-issue-tracker.toml for a starting template covering ticket regex, service allowlist, redaction extras, and ticket-link base URL.

---

Architecture

   ┌────────────────────────┐
   │  Any MCP Client (stdio) │
   └──────────┬─────────────┘
              │
              ▼
   ┌─────────────────────────────────┐
   │  lograft (this package)          │
   │   parse_kql ─┐                   │
   │   normalize ─┼─► correlate ─┐    │
   │   gather    ─┘              │    │
   │                   redactor  │    │   ← internal middleware (D13)
   │                             ▼    │
   │                       render md/json/html
   └─────────────────────┬───────────┘
                         │ subprocess (live mode only)
                         ▼
            ┌──────────────────────────────┐
            │  azmcp (microsoft/mcp, GA)    │
            │  Owns Azure auth + KQL exec.  │
            └──────────────────────────────┘

Trust boundaries:

• lograft never holds Azure credentials. Live mode = subprocess to azmcp.
• The redactor is the SOLE chokepoint between log content and any output file.
• stdout is reserved for MCP JSON-RPC. All logs go to stderr. A runtime guard throws if anything else writes to stdout.

---

Caps and defaults

Setting	Default	Rationale
Max correlated rows	1000	bounded report size
Max commits considered	200	bounded git log
Max output file size	5 MB	bounded share-ability
Tiebreaker window	±10 min	timestamp proximity, AFTER key match
azmcp subprocess timeout	5 min	bounded live mode
Repo lookback	14 days	recent context only

All are TOML-configurable; none are removable.

---

Roadmap (Phase 2)

• Datadog / CloudWatch / Loki / Elastic LogSourceAdapter implementations
• Slack / Teams webhook output
• Live Jira / GitHub API ticket enrichment (replaces regex-only extraction)
• Public MCP registry submission to modelcontextprotocol.io
• Multi-query batch mode
• lograft_preview_redaction tool — read-only diff for audit

---

Contributing

Pull requests are welcome — especially new LogSourceAdapter implementations.

Before submitting:

pnpm install
pnpm test
pnpm typecheck
pnpm lint
pnpm build

See CONTRIBUTING.md for adapter contracts and commit conventions.

Security reports: do not open public issues. See SECURITY.md.

---

License

MIT © Hoài Nhớ