# Nusawave MCP Server

MCP tools to read local git repos and fetch public web pages — no SerpAPI or Firecrawl required.

One shared `server.py` runs as **multiple MCP servers** (one process per repo), configured via environment variables or JSON config files.

## Tools

| Tool | What it does |
|------|----------------|
| `get_repo_overview` | README + key root files when present |
| `list_docs` | List markdown files under `docs/` |
| `read_repo_file` | Read any file inside the configured repo |
| `fetch_public_page` | HTTP fetch any public URL → plain text |
| `audit_live_site` | Fetch live site sections — only when `NUSAWAVE_SITE_URL` is set |

## Quick start

```bash
git clone https://github.com/YOUR_ORG/nusawave-mcp.git
cd nusawave-mcp

python3 -m venv .venv
source .venv/bin/activate
pip install -e .

# Test on stdio (Ctrl+C to stop)
NUSAWAVE_REPO_PATH=/path/to/your/repo python server.py
```

Or with [uv](https://docs.astral.sh/uv/):

```bash
uv sync
NUSAWAVE_REPO_PATH=/path/to/your/repo uv run server.py
```

## Environment variables

| Variable | Default | Purpose |
|----------|---------|---------|
| `NUSAWAVE_MCP_NAME` | `nusawave` | FastMCP server name (set per config entry) |
| `NUSAWAVE_REPO_PATH` | `.` | Local clone path for this server process |
| `NUSAWAVE_SITE_URL` | _(unset)_ | Live site base URL; required for `audit_live_site` |

## Example: Nusawave projects

The maintainers run one server entry per repo. Copy the example config and adjust paths:

```bash
cp typingmind-mcp-config.example.json typingmind-mcp-config.json
# edit paths in typingmind-mcp-config.json
```

| Server key | Example repo | `audit_live_site` |
|------------|--------------|-------------------|
| `nusawave-labs-website` | `nusawave-labs.github.io` | Yes |
| `nusawave-forecast` | `nusawave-forecast` | No |
| `nusawave-extract-point` | `extract-point` | No |
| `nusawave-io` | `nusawave.io` | No |
| `nusawave-brainstormingxclaude` | `brainstormingxclaude` | No |

## Connect to Claude CLI

From this repo directory:

```bash
claude mcp add my-project \
  -e NUSAWAVE_MCP_NAME=my-project \
  -e NUSAWAVE_REPO_PATH=/path/to/your/repo \
  -- /path/to/venv/bin/python /path/to/nusawave-mcp/server.py

claude mcp get my-project
```

Then run `claude` and ask it to use your MCP tools, e.g. “Use my-project to get the repo overview.”

## Connect to Claude Desktop (Windows + WSL)

If Claude Desktop runs on Windows but the repo lives in WSL, use a UNC path for `--directory` or invoke WSL explicitly. See `examples/claude-desktop-config.json`.

Minimal WSL example (merge into `%APPDATA%\Claude\claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "nusawave-my-project": {
      "command": "wsl",
      "args": [
        "-d", "Ubuntu", "--",
        "/home/USER/apps/mcp/nusawave/.venv/bin/python",
        "/home/USER/apps/mcp/nusawave/server.py"
      ],
      "env": {
        "NUSAWAVE_MCP_NAME": "nusawave-my-project",
        "NUSAWAVE_REPO_PATH": "/home/USER/apps/your-repo"
      }
    }
  }
}
```

Restart Claude Desktop after editing the config.

## Connect to TypingMind

### 1. Start the MCP connector

```bash
./start-connector.sh YOUR_AUTH_TOKEN
```

Use the **same token** shown in TypingMind → Settings → MCP. The script prints the exact URL to paste.

**Critical:** Connector URL must include the port:

| URL | Result |
|-----|--------|
| `http://127.0.0.1:50880` | Correct |
| `http://localhost:50880` | Correct |
| `http://localhost` | Wrong — hits nginx on port 80 → **404 / "Update required"** |
| `http://0.0.0.0:50880` | Wrong — browsers cannot connect to `0.0.0.0` |

Verify with:

```bash
./verify-connector.sh http://127.0.0.1:50880 YOUR_AUTH_TOKEN
```

### 2. TypingMind settings

1. **Settings → Advanced → Model Context Protocol**
2. **Delete and re-setup MCP Connector** (clears stale URL)
3. Choose **Private MCP Connector** (not TypingMind Cloud)
4. Paste connector URL and auth token from step 1
5. Wait for green check / Get Started

### 3. Add local MCP servers

Click **Edit Servers** and paste your `typingmind-mcp-config.json` (copy from `typingmind-mcp-config.example.json` first).

### 4. Enable plugins

**Plugins** → enable the servers you need → attach to your character.

> **"Update required… restart MCP Connector"** — TypingMind got **404** on `/mcp-connect`. Almost always a **wrong Connector URL** (missing `:50880`).

### WSL note

If TypingMind runs in **Windows** but this repo is in **WSL**, run the MCP connector inside WSL. Paths in the config must be valid on the machine where Python runs.

## Example prompts

- "Get the repo overview for my forecast project"
- "Read docs/index.md and compare with the live site"
- "Summarize the repository structure"
- "Fetch https://example.github.io/ and summarize the homepage"

## License

MIT — see [LICENSE](LICENSE).