# hosting-doctor-mcp

An [MCP](https://modelcontextprotocol.io) server that diagnoses web hosting and server problems by
combining **live diagnostic checks** (HTTP, SSL, DNS, security headers) with a **RAG-searchable
knowledge base** of troubleshooting notes, stored in [Weaviate](https://weaviate.io).

Point Claude, Cursor, or any other MCP client at a URL and a symptom ("visitors see a blank white
page", "certificate warning in the browser", "site went down after I changed nameservers") and it
gets back live evidence plus the most relevant troubleshooting notes — then reasons over both to
explain what's actually wrong, instead of guessing from the symptom text alone.

## Why this exists

Most "AI + hosting" tools fall into one of two buckets: an official API wrapper (DigitalOcean,
WordPress, and Weaviate all already ship their own MCP servers for CRUD-style operations against
their own platforms), or a generic Lighthouse/PageSpeed wrapper (several of these already exist
too). Neither actually diagnoses anything — they just expose an API.

`hosting-doctor-mcp` is a synthesis tool instead: it runs the live checks *and* retrieves the
relevant troubleshooting context in one call, then leaves the actual reasoning to the calling
agent, which has the full conversation and can explain the result in plain language. That
retrieval-not-generation split is deliberate — the tool's job is to gather evidence, not to write
the final answer.

## Tools

| Tool | What it does |
|---|---|
| `check_http_status` | Live HTTP request: status code, latency, full redirect chain |
| `check_ssl` | Live TLS handshake: issuer, validity window, days until expiry, SANs |
| `check_dns` | Live DNS lookups: A / AAAA / CNAME / MX / TXT / NS |
| `check_security_headers` | Checks response headers against CSP / HSTS / X-Content-Type-Options / X-Frame-Options / Referrer-Policy / Permissions-Policy |
| `search_troubleshooting_kb` | Hybrid vector + keyword search over a curated knowledge base of hosting issues |
| `diagnose` | Orchestrator: runs all four live checks and a KB search in parallel, returns one structured report |

The knowledge base (`kb/*.md`) currently covers 17 issues: 502/504 gateway errors, mixed content
warnings, WordPress white screen of death, DNS propagation delays, SSL chain issues, CORS errors,
high TTFB, redirect loops, CDN cache staleness, PHP memory limit errors, 429 rate limiting, Let's
Encrypt renewal failures, generic 500 errors, email deliverability (SPF/DKIM/DMARC), disk space
exhaustion, connection-refused/port issues, and database connection pool exhaustion. Each note is
frontmatter (title, tags, symptoms) plus a short cause-and-fix body — see `kb/` to read or extend
them.

## Architecture

```
MCP client (Claude Desktop / Cursor / Claude Code)
        │  stdio (JSON-RPC)
        ▼
hosting-doctor-mcp server (Node + TypeScript, @modelcontextprotocol/sdk)
    ├── check_http_status / check_ssl / check_dns / check_security_headers
    │     → Node built-ins only (fetch, tls, dns/promises) — zero external deps
    │
    └── search_troubleshooting_kb / diagnose
          → Weaviate Cloud (hybrid search, text2vec-weaviate hosted embeddings)
```

The four live-check tools have no external dependencies and work immediately. The KB search
depends on a Weaviate Cloud sandbox — see setup below.

## Setup

### 1. Install and build

```bash
git clone https://github.com/huzaifashuja/hosting-doctor-mcp.git
cd hosting-doctor-mcp
npm install
npm run build
```

### 2. (Optional but recommended) Set up the knowledge base

The KB search and `diagnose` tools need a [Weaviate Cloud](https://console.weaviate.cloud) sandbox
(free tier is enough):

1. Create a free sandbox cluster at console.weaviate.cloud.
2. Copy `.env.example` to `.env` and fill in `WEAVIATE_URL` and `WEAVIATE_API_KEY` from the
   sandbox's dashboard.
3. Ingest the knowledge base:

   ```bash
   npm run ingest
   ```

Without this step, the four live-check tools still work fine — `search_troubleshooting_kb` and
`diagnose` will just report the KB as unavailable.

### 3. Connect it to an MCP client

**Claude Desktop** — add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "hosting-doctor": {
      "command": "node",
      "args": ["/absolute/path/to/hosting-doctor-mcp/dist/src/index.js"],
      "env": {
        "WEAVIATE_URL": "https://your-cluster-id.weaviate.network",
        "WEAVIATE_API_KEY": "your-weaviate-api-key"
      }
    }
  }
}
```

**Cursor** — add the same shape to `.cursor/mcp.json` in your project (or the global Cursor MCP
config).

**Claude Code** — `claude mcp add hosting-doctor -- node /absolute/path/to/hosting-doctor-mcp/dist/src/index.js`

### 4. Try it

Ask your MCP client something like:

> My site example.com is showing a certificate warning, can you check what's wrong?

or

> Diagnose why mysite.com is showing a blank white screen.

## Development

```bash
npm run dev       # run the server directly with tsx (no build step)
npm run inspect   # build, then open the MCP Inspector for manual tool testing
npm run ingest    # re-ingest kb/*.md into Weaviate (safe to re-run)
```

## Project structure

```
src/
  index.ts                 # MCP server entrypoint, tool registration
  tools/
    checkHttpStatus.ts
    checkSsl.ts
    checkDns.ts
    checkSecurityHeaders.ts
    searchKb.ts
    diagnose.ts
  lib/
    weaviateClient.ts       # Weaviate connection + collection schema
  types.ts
kb/
  *.md                      # curated troubleshooting notes
scripts/
  ingest.ts                 # chunks + upserts kb/*.md into Weaviate
```

## License

MIT