opsdoctor-mcp

OpsDoctor MCP Server

Version: 2.1.0 Runtime: Node.js + TypeScript (tsx) AI Backend: Google Gemini 2.5 Flash Protocol: Model Context Protocol (MCP) via stdio transport Owner: Resolution AI (resolutionai.solutions)

OpsDoctor is an AI-powered operations diagnostic and workflow audit tool built as an MCP server. It provides structured CRM troubleshooting, multi-stage workflow assessments, an embedded knowledge base, persistent audit history, and branded PDF report generation — all callable as MCP tools from any compatible client (Claude Code, Claude Desktop, etc.).

Tools

OpsDoctor exposes 6 MCP tools:

1. run_diagnostic

Diagnose a CRM or operational issue using AI. Returns a structured report with root causes, step-by-step fixes, verification steps, and prevention tips.

Parameter	Type	Required	Description
crm_name	string	Yes	CRM system name (e.g. HubSpot, Salesforce, Zoho, Go High Level, Dubsado)
symptoms	string	Yes	Description of the issue or symptoms
company_context	string	No	Company size, team structure, or other relevant context
industry	enum	No	Industry vertical for context-aware diagnostics
client_name	string	No	Client or company name for history tracking

What it does:

• Looks up the CRM from a library of 39 platform-specific diagnostic profiles with detailed focus areas, common patterns, and known issues
• When an industry is specified, enriches the prompt with industry-specific knowledge base entries (discovery areas, red flags, technology stack)
• Sends the assembled context to Gemini for structured analysis
• Auto-persists the result to audit history

Supported CRMs (39): Acculynx, ActiveCampaign, Airtable, Apptivo, Bitrix24, Buildertrend, Capsule, ClickUp, Close, CoConstruct, CompanyCam, Contractor Foreman, Copper, Creatio, Dubsado, EnrollTools, FieldPulse, Freshsales, GoHighLevel, HoneyBook, HubSpot, Insightly, Jobber, Keap, Less Annoying CRM, Microsoft Dynamics 365, Monday.com, NetSuite, Nimble, Ontraport, Oracle CX, Pipedrive, Procore, Salesforce, SAP Sales Cloud, ServiceTitan, SugarCRM, Zendesk, Zoho

2. run_workflow_audit

Audit an operational workflow. Supports 4 modes for different levels of depth.

Parameter	Type	Required	Description
workflow_description	string	Yes	Description of the workflow or process to audit
industry	string	No	Industry vertical (e.g. real-estate, insurance, legal)
team_size	string	No	Approximate team size
mode	enum	No	quick (default), intake, assess, or followup
intake_answers	object	For assess/followup	7 structured intake answers
previous_scores	object	For followup	Dimension scores from the assess stage
followup_answers	string	For followup	Answers to follow-up questions from assess
client_name	string	No	Client name for history tracking

Modes:

Mode	AI Call	Description
quick	Yes	Single-pass audit. Returns an efficiency score (0-100), executive summary, bottlenecks, automation opportunities, risk assessment, and a 90-day action plan. Includes reference baseline comparison.
intake	No	Returns 7 structured discovery questions tailored to the industry. No AI call — instant response.
assess	Yes	Processes intake answers through AI for dimensional scoring across 4 dimensions (Efficiency 30%, Automation Readiness 25%, Risk Exposure 25%, Scalability 20%). Returns a weighted composite score, per-dimension findings, top issues, reference baseline comparison, and follow-up questions. Scoring uses calibrated rubrics with explicit anchors at each tier.
followup	Yes	Deep-dive second pass. Takes the original intake answers, previous dimension scores, and answers to follow-up questions. Returns revised scores with change explanations, updated findings, and a comprehensive prioritized action plan. Scoring uses the same calibrated rubrics as the assess stage.

Scoring:

Score Range	Health Label
80-100	Healthy
60-79	Needs Attention
40-59	At Risk
0-39	Critical

3. guided_audit

A structured multi-stage wrapper around run_workflow_audit that guides the LLM through the full audit flow. Each stage returns results plus explicit instructions for the next stage. Stateless — the LLM carries forward all context between calls.

Parameter	Type	Required	Description
stage	enum	Yes	start, assess, followup, or complete
workflow_description	string	Yes	Workflow description (carry forward through all stages)
industry	string	No	Industry vertical
team_size	string	No	Approximate team size
client_name	string	No	Client name for history tracking
intake_answers	object	For assess+	The 7 intake answers
previous_scores	object	For followup+	Scores from the assess stage
followup_answers	string	For followup+	Follow-up question answers

Stage flow:

start → (user answers 7 questions) → assess → (user answers follow-ups) → followup → complete

Each stage's output includes a "Next Step" block telling the LLM exactly which tool to call next, which parameters to carry forward, and what data to collect from the user.

4. query_knowledge_base

Search the embedded knowledge base for discovery questions, red/green flag guides, conversation scripts, technology stack references, data governance guidance, and vendor management entries. No AI call — instant keyword search over embedded content.

Parameter	Type	Required	Description
query	string	Yes	What to look up (e.g. "lead management red flags")
category	enum	No	Filter: discovery, red-flags, green-flags, scripts, technology-stack, data-governance, vendor-management, or all
industry	enum	No	Filter: general, real-estate, legal, insurance, streaming-entertainment, production, dental, home-services, or all

Knowledge base stats:

• 330 entries across 8 industry verticals
• 7 content categories per vertical
• 8 industries: General (cross-industry), Real Estate, Legal, Insurance, Streaming & Entertainment, Production (Film/Video/Events), Dental, Home Services

5. get_audit_history

Retrieve past diagnostic and audit results from the persistent JSONL store. Results include audit IDs that can be passed to generate_report for PDFs.

Parameter	Type	Required	Description
client_name	string	No	Filter by client name (case-insensitive partial match)
type	enum	No	Filter: diagnostic, quick-audit, assess-audit, followup-audit, or all (default)
limit	number	No	Maximum results to return (default: 10, most recent first)

What it returns:

• Numbered list of past results, most recent first
• Each entry shows: type, client name, timestamp (Mountain Time), key metrics (score, health label, score changes for follow-ups), and audit ID
• PDF indicator for entries that have a generated report

6. generate_report

Generate a branded PDF report from a diagnostic or audit result. Accepts an audit ID (loads from history) or inline result data. Writes the PDF to disk and returns the file path.

Parameter	Type	Required	Description
audit_id	string	No	ID of a history entry (from get_audit_history). Mutually exclusive with inline data.
report_type	enum	No	diagnostic or audit. Required if providing inline data.
report_data	string	No	JSON string of the structured result. Required if audit_id is not provided.
client_name	string	No	Client name for the report filename

Output: PDF saved to ~/opsdoctor-data/reports/ with naming pattern OpsDoctor_{Type}_{Client}_{Date}.pdf. The history entry is updated with the PDF path.

Scoring Rubrics

All audit prompts include calibrated scoring rubrics with explicit anchors defining what each score range (0-19, 20-39, 40-59, 60-79, 80-100) looks like for each dimension. This prevents score inflation, ensures consistency across runs, and produces scores that are meaningful relative to the reference baselines. The full rubric is in src/data/scoring-rubric.ts (DIMENSIONAL_RUBRIC for assess/followup, QUICK_RUBRIC for quick mode).

Reference Baselines

Audit results include comparative reference baselines for the selected industry. These are informed estimates for service-based SMBs — not statistically validated industry averages — and are clearly labeled as such in all output.

Industry	Efficiency	Automation Readiness	Risk Exposure	Scalability	Composite
General (Cross-Industry)	55	40	50	45	48
Real Estate	52	38	45	42	45
Legal	58	35	55	40	48
Insurance	60	45	58	48	54
Streaming & Entertainment	50	48	42	55	49
Production (Film/Video/Events)	48	35	40	38	41
Dental	65	50	60	50	57
Home Services	52	38	42	40	44

Data & Persistence

• Audit history: ~/opsdoctor-data/audit-history.jsonl (JSONL, one entry per line)
• PDF reports: ~/opsdoctor-data/reports/
• Data directory is configurable via the OPSDOCTOR_DATA_DIR environment variable
• All results (diagnostics and audits) are automatically persisted on every run

Configuration

Environment Variables

Variable	Required	Description
GEMINI_API_KEY	Yes (for AI tools)	Google Gemini API key. Without it, run_diagnostic, run_workflow_audit (quick/assess/followup modes), and guided_audit (assess/followup stages) will return an error message. The knowledge base and audit history tools work without it.
OPSDOCTOR_DATA_DIR	No	Override the default data directory (~/opsdoctor-data)

Running

# Development
npm run dev

# Build + run compiled
npm run build
node dist/index.js

MCP Client Configuration

{
  "mcpServers": {
    "opsdoctor": {
      "command": "npx",
      "args": ["tsx", "src/index.ts"],
      "cwd": "/path/to/studio-a/mcp-servers/opsdoctor",
      "env": {
        "GEMINI_API_KEY": "your-key-here"
      }
    }
  }
}

Architecture

src/
  index.ts                  MCP server entry point (stdio transport)
  gemini.ts                 Gemini API client wrapper (never throws)
  types.ts                  Shared TypeScript types for all result formats
  paths.ts                  Deterministic path resolution for data/output dirs
  store.ts                  JSONL persistence (append, load, filter, update)
  tools/
    diagnostic.ts           run_diagnostic — CRM issue diagnosis
    workflow-audit.ts        run_workflow_audit — multi-mode workflow audit
    guided-audit.ts          guided_audit — structured multi-stage wrapper
    knowledge-base.ts        query_knowledge_base — keyword search over KB
    audit-history.ts         get_audit_history — history retrieval
    generate-report.ts       generate_report — PDF generation
  data/
    crm-profiles.ts          39 CRM diagnostic profiles
    benchmarks.ts            Industry reference baselines
    scoring-rubric.ts        Calibrated scoring anchors for audit prompts
    kb-entries.ts            KB entry type definitions + aggregation
    kb/
      general.ts             29 cross-industry KB entries
      real-estate.ts         43 real estate KB entries
      legal.ts               43 legal KB entries
      insurance.ts           43 insurance KB entries
      streaming-entertainment.ts  43 streaming/entertainment KB entries
      production.ts          43 production KB entries
      dental.ts              43 dental KB entries
      home-services.ts       43 home services KB entries
  pdf/
    report-generator.ts      PDFKit-based branded report generation

Dependencies

Package	Purpose
@modelcontextprotocol/sdk	MCP server framework
@google/genai	Google Gemini AI client
pdfkit	PDF report generation
zod	Input schema validation