jasmin-core-enigma/local_mcp_server

Local MCP Server for Project Docs and Error Handler Integration

This MCP server feeds your project documentation directly to GitHub Copilot Chat and adds Error Handler–specific helpers so teams can integrate and verify errors quickly and consistently.

Vision

• Make the full Error Handler (EH) integration seamless and fast for customers.
• Prefer Sphinx HTML docs for precise section reads; support Markdown/RST/INC/PDF.
• Scope context by use-case profiles (start with Error Handler) to keep answers focused.
• Provide task-oriented tools: search docs, jump to sections, list EH hosts, map error IDs to generated headers and macros, and a concise integration guide.

Current Functionality

The server runs over stdio and auto-discovers docs based on .copilot/mcp.config.json. Available tools:

• search_docs(query, useCase?) — Search across configured docs (HTML preferred), optionally scoped to a use case.
• list_use_cases() — List available use-case profiles from .copilot/usecases.
• activate_use_case(name) — Return an overview (key docs + hints) for a use case.
• get_project_overview() — Sample of top docs to get oriented.
• read_doc_section({ doc, anchor?, heading?, useCase? }) — Extract a specific section from an HTML doc (by anchor or heading) or fall back to text snippets.
• eh_list_hosts() — Scan generated EH headers and list available hosts (e.g., SH00).
• eh_lookup_error({ uid, listPath?, host? }) — Given an error UID (symbolic name), find the generated header/macro and show include + usage guidance for a host.
• error_handler_guide({ errorName, useCase? }) — Step-by-step EH integration checklist for a specific error.
• eh_run_generators({ dryRun?, timeoutSec?, extra? }) — Run the Genie trio to produce EH artifacts (no host args needed).

Under the hood:

• Watches configured roots and caches parsed content for fast retrieval.
• Converts HTML/PDF to text; reads md/rst/inc as plain text.

Quick Start

• Build once:
  • npm run build
• Start (stdio):
  • npm start
• Dev (watch):
  • npm run dev

VS Code/Copilot Chat integration: use the ready-made templates under templates/ to register the server so Copilot Chat auto-starts it. See templates/README-templates.md for copy-paste steps.

By default, the server searches upward for a .copilot/ folder to locate the project root and reads .copilot/mcp.config.json.

Configuration

Create .copilot/mcp.config.json at the project root. Example (abridged):

{
  "contextRoots": [
    ".copilot",
    "1000-Documentation/1010-user-manual/user_documentation/_build/html",
    "1000-Documentation/1010-user-manual/user_documentation/MotionWiseServicesClassic"
  ],
  "include": ["**/*.md", "**/*.rst", "**/*.inc"],
  "exclude": ["**/node_modules/**", "**/dist/**", "**/.git/**"],
  "eh": {
    "headersRoot": "1700-Configuration/<...>/errorhandler/code", 
    "listsRoot": "1900-sysdef/RDB2",
    "defaultHost": "SH00"
  }
}

Use-case profiles live in .copilot/usecases/*.json (see templates/usecases/error_handler.json). They scope roots/patterns and provide hints.

Error Handler Use Case: End-to-end Flow

1. Define the error in the 1900-sysdef error lists (JSON). Choose the correct list and add your ERROR_NAME with attributes (severity, category, reporter, hosts).
2. Generate EH artifacts (inside your Docker/Genie env):
   • genie invariant_error_ID
   • genie gen_eh
   • genie gen_eh_dataset
3. Include the generated EH header in your 1800 application for the target host:
   • Example include: #include <EH_ErrorIDMapping_<suffix>.h>
   • Use the macro: EH_ReportError(ERROR_ID_<ERROR_NAME>, context);
4. Build and verify; ensure the generated headers are on the include path and run platform tests as needed.

Helpful tools during the flow:

• eh_list_hosts → confirm available hosts after generation.
• eh_lookup_error({ uid: "ERROR_NAME", host: "SH00" }) → get exact header/macro and example usage.
• read_doc_section({ doc: "ErrorHandler.html", heading: "API" }) → pull the right API section from Sphinx HTML.
• eh_run_generators({ dryRun: true }) → preview commands; omit dryRun to execute.

Running EH Generators via MCP

Assumptions:

• Your environment has either:
  • genie available in PATH inside your current shell, or
  • the project’s docker_run_interactively.sh and entrypoint.sh at repo root to run commands in-container.

What it does:

• Executes in order: genie invariant_error_ID → genie gen_eh → genie gen_eh_dataset.
• If genie isn’t found, wraps each with bash ./docker_run_interactively.sh -- <cmd>.
• On success, it reports detected artifacts under the configured EH headersRoot and lists hosts.

Inputs and behavior:

• Input to the generators is your EH error lists (JSON) under listsRoot (e.g., 1900-sysdef/.../EH_*.json).
• Add a new list or error entry, then run the generators — they will derive hosts, mappings, and produce updated headers automatically. No host parameter is required.

Usage examples:

• Dry run (show planned commands):
  • eh_run_generators({ "dryRun": true })
• Execute with a 20-minute timeout:
  • eh_run_generators({ "timeoutSec": 1200 })
• Pass extra args to each genie command (advanced):
  • eh_run_generators({ "extra": "--verbose" })

How to Extend

• Add new use cases: create JSON profiles under .copilot/usecases/ with focused roots/filters and hints.
• Add new tools: extend src/index.ts (register in ListTools; implement in the CallTool handler). Keep inputs small and deterministic.
• Add new content roots: update .copilot/mcp.config.json contextRoots/include/exclude. Prefer Sphinx HTML for precise section extraction.
• Add new readers: the server converts HTML/PDF to text already; extend readAsText for other formats if needed.

Notes

• HTML is converted to text for semantic search and section extraction; PDFs are parsed to text. Prefer HTML when available for best results.
• The server watches configured roots and refreshes its cache on file changes.

See templates/README-templates.md to wire this into VS Code so GitHub Copilot Chat can call these tools automatically in your workspace.