gvauter/gemara-mcp-server

Gemara MCP Server (SSE Adapter)

Minimal MCP-style server that exposes Gemara authoring and conversion tools over SSE and proxies requests to your Gemara HTTP backend.

Endpoints (MCP adapter)

• GET /sse: announces available tools (MCP-compatible SSE).
• POST /message: invokes a tool by name with JSON payload and returns the result.

Tools (generic, layer-agnostic)

• convert_to_gemara:
  • args: { "layer": 1|2|3, "framework": "string", "text": "string" }
  • result: Gemara artifact (JSON parsed from YAML).
  • description: Converts source text (e.g., extracted from a PDF/DOCX) into a Gemara artifact for the specified layer. Uses LLM with strict CUE schema validation and a repair loop (in the backend).
  • example MCP call payload:

    {
      "id": "1",
      "tool": "convert_to_gemara",
      "args": {
        "layer": 1,
        "framework": "PCI DSS",
        "text": "1. Install and maintain a firewall configuration...\n1.1 Establish and implement firewall rules..."
      }
    }
    

  • example user prompt (for an MCP-aware assistant): “Convert this PCI section into a valid Gemara Layer 1 YAML artifact.”
• author_gemara:
  • args: { "layer": 1|2|3, "framework": "string", "instructions": "string" }
  • result: Gemara artifact.
  • description: Authors a new Gemara artifact from natural-language instructions (no source text), for the specified layer. Enforces YAML-only output and strict schema in the backend.
  • example MCP call payload:

    {
      "id": "2",
      "tool": "author_gemara",
      "args": {
        "layer": 2,
        "framework": "OSPS Baseline",
        "instructions": "Create 3 concise controls for CI pipeline security: signed artifacts, dependency scanning, and SBOM publication."
      }
    }
    

  • example user prompt: “Author a Gemara Layer 2 control set for CI pipeline security with 3 controls.”
• validate_gemara:
  • args: { "layer": 1|2|3, "artifact": { ... } }
  • result: { "ok": true } or { "ok": false, "error": "..." }.
  • description: Validates an artifact against the Gemara CUE schema for the specified layer. Requires GEMARA_SCHEMA_DIR configured on the backend. For Layer 1, the backend can also do a structural fallback.
  • example MCP call payload:

    {
      "id": "3",
      "tool": "validate_gemara",
      "args": {
        "layer": 1,
        "artifact": {
          "$schema": "https://github.com/ossf/gemara/schemas/layer1",
          "framework": "PCI DSS",
          "guidelines": [{ "id": "1", "title": "Install and maintain a firewall", "text": "" }]
        }
      }
    }
    

  • example user prompt: “Check that this Gemara document is valid for Layer 1.”
• repair_gemara:
  • args: { "layer": 1|2|3, "framework": "string", "yaml": "string", "error": "string" }
  • result: Gemara artifact.
  • description: Given invalid Gemara YAML and a validation error message, asks the LLM to minimally repair the YAML, then re-validates.
  • example MCP call payload:

    {
      "id": "4",
      "tool": "repair_gemara",
      "args": {
        "layer": 3,
        "framework": "Security Policy",
        "yaml": "framework: Security Policy\npolicies:\n- title: Missing id\n",
        "error": "policies[0].id is required"
      }
    }
    

  • example user prompt: “Fix this Layer 3 YAML so it passes schema validation. Only minimal changes.”
• merge_gemara:
  • args: { "layer": 1|2|3, "framework": "string", "artifacts": [ ... ] }
  • result: Gemara artifact (implemented for layer 1).
  • description: Merges multiple artifacts into a single one. Currently implemented for Layer 1 (de-duplicates by id+title, preserves framework if provided).
  • example MCP call payload:

    {
      "id": "5",
      "tool": "merge_gemara",
      "args": {
        "layer": 1,
        "framework": "PCI DSS",
        "artifacts": [
          { "$schema": ".../layer1", "framework": "PCI DSS", "guidelines": [{ "id": "1", "title": "Firewall", "text": "" }] },
          { "$schema": ".../layer1", "framework": "PCI DSS", "guidelines": [{ "id": "1", "title": "Firewall", "text": "" }, { "id": "2", "title": "Passwords", "text": "" }] }
        ]
      }
    }
    

  • example user prompt: “Merge these two Layer 1 fragments and remove duplicates.”

Tools (L1 legacy, kept for compatibility)

• convert_to_layer1, author_layer1, repair_layer1, validate_layer1, merge_layer1.
  • description: Layer-1-specific variants of the generic tools above. Useful for older client setups. Prefer generic tools for future-proofing.

Requirements

• A running Gemara HTTP backend (from gemara-cli cmd/server) exposing:
  • /v1/convert_to_gemara, /v1/author_gemara, /v1/validate_gemara, /v1/repair_gemara, /v1/merge_gemara, plus legacy L1 endpoints.
• Strict schema validation (recommended):
  • Set GEMARA_SCHEMA_DIR for the backend to the Gemara schemas root (e.g. /home/.../ossf/gemara/schemas).

Run

1. Start the Gemara backend (in the gemara-cli repo):

export GEMARA_SCHEMA_DIR=/path/to/ossf/gemara/schemas
./bin/server

2. Start the MCP adapter (this repo):

./bin/gemara-mcp --addr :8090 --backend http://localhost:8080

You can also set GEMARA_HTTP_BACKEND_URL instead of --backend.

Quick test (without an MCP host)

• List tools (SSE stream in a browser or curl): http://localhost:8090/sse
• Invoke a tool:

curl -s http://localhost:8090/message \
  -H 'Content-Type: application/json' \
  -d '{
        "id":"1",
        "tool":"convert_to_gemara",
        "args":{
          "layer":1,
          "framework":"PCI DSS",
          "text":"1. Install and maintain a firewall configuration..."
        }
      }'

MCP host config (example)

Point your MCP-capable client to the SSE endpoint, e.g.:

{
  "mcpServers": {
    "gemara": {
      "url": "http://localhost:8090/sse"
    }
  }
}

This adapter only brokers requests; all schema enforcement and LLM work are performed by the Gemara HTTP backend.