mcp-home-server

Single, stable Model Context Protocol (MCP) "door" server that runs on your home machine and exposes a dynamic set of tools to every connected AI client (desktop, phone, future agents). Tools can be added, edited, or removed at runtime — no restart needed.

Behind the door:

• Dynamic tool loader watches src/tools/ and hot-reloads each module via chokidar + the MCP SDK's list_changed notification.

• JSON manifest is regenerated automatically and served at GET /manifest.

• URLTracker ingests "AI usage" events, hashes them, and emits a url_tracker:new_ai event the first time a URL is seen.

• Onboarding agent listens to those events and writes per-AI onboarding payloads (manifests/onboarding/<hash>.json) so new clients can instantly configure themselves to use this MCP host.

• Scouting worker periodically scans configured roots (SCOUT_ROOTS) for scripts/modules that look like MCP tool candidates; proposals are written to manifests/pending/ for human review (no auto-promotion).

• Dedupe worker compares registered tools and writes overlap reports to docs/dedupe/ to surface merges/refactors.

Quick start

git clone https://github.com/manniegreenspan/mcp-home-server.git
cd mcp-home-server
npm install
npm run dev
# Server binds 127.0.0.1 on the first free port in 7000-7999.
# Check console for the actual URL, e.g.: http://127.0.0.1:7432/mcp

Test it with the MCP Inspector:

npx @modelcontextprotocol/inspector@latest
# Paste the MCP endpoint URL into the inspector.

Endpoints

Adding a tool

Drop a file in src/tools/:

// src/tools/hello-world.ts
import { z } from "zod";
import type { ToolModule } from "../lib/types";

export default {
  name: "hello_world",
  description: "Says hello to a name",
  inputSchema: { name: z.string().describe("Name to greet") },
  handler: async ({ name }) => ({
    content: [{ type: "text", text: `Hello, ${name}!` }]
  })
} satisfies ToolModule;

The loader picks it up immediately, registers it with the MCP server, and sends the notifications/tools/list_changed notification. Connected clients (Inspector, Claude Desktop, etc.) refresh their tool list automatically.

Delete the file → tool unregistered. Edit the file → tool re-registered.

Cloudflare deployment

See docs/DEPLOYMENT.md. v1 recommends Cloudflare Tunnel fronting the local Express server. A pure-Cloudflare-Worker rewrite is in the ROADMAP (Workers can't do dynamic import() of src/tools/*.ts).

Project layout

mcp-home-server/
├── src/
│   ├── server.ts               # main entry: Express + McpServer + transports
│   ├── ports.ts                # port scan 7000-7999
│   ├── manifest.ts             # generate/serve JSON manifest
│   ├── logger.ts               # pino instance
│   ├── event-bus.ts            # shared EventEmitter
│   ├── tools/                  # dynamic tool modules (one file per tool)
│   ├── workers/                # onboarding-agent, scouting-worker, dedupe-worker
│   ├── url-tracker/            # ingestion + detector + hash store
│   └── lib/                    # types, hashing
├── manifests/
│   ├── current.json            # auto-regenerated manifest
│   ├── pending/                # scout proposals (manual review)
│   └── onboarding/             # onboarding payloads written by agent
├── docs/
│   ├── DEPLOYMENT.md
│   ├── ARCHITECTURE.md
│   └── dedupe/                 # dedupe-worker reports
├── tests/
└── logs/

License

MIT — see LICENSE.