mcp-toolkit-hub: Instructions file for Claude Code

CLAUDE.md

_context:
  tier: distributable  # MCP package for others to use
  version: 0.5.0
  last_updated: 2026-02-10

MCP hub server that aggregates tools from multiple domain packages into a single globally-available interface.

Purpose

This package provides a hub that exposes tools from multiple domain packages (content-feed, travel, etc.) through a single MCP server. When configured at the user level, tools work globally regardless of which directory Claude Code is started from.

Why a hub? Without it, each MCP package needs separate configuration, and tools only work in specific project directories. The hub pattern gives you one config, global availability.

Architecture

User Config (~/.config/mcp-toolkit-hub/config.yaml)
         ↓
   mcp-toolkit-hub (this package)
         ↓
   Domain Packages (mcp-content-feed, mcp-travel, etc.)

Key Constraints

• Distributable — Generic orchestration logic; user config is personal
• Delegates, doesn't duplicate — Business logic stays in domain packages. This package only routes.
• Namespaced tools — Tools are prefixed with package name: briefing_run_weekly_digest (underscores, not colons — MCP spec limitation)

Defensive Coding Standards

This package loads and delegates to other packages — it's the trust boundary between user config, domain packages, and LLM-generated tool calls. Apply defensive thinking to all code changes.

Security-Sensitive Areas

Config Loading (src/lib/config.ts)

• Config is YAML from user files — may be hand-edited, malformed, or missing
• Validate structure with Zod schema: actionable error messages for every validation failure
• Handle missing config file: clear error with path ("Config not found at [path]. Create from example at [example path]")
• Handle malformed YAML: surface parse error with line number if possible
• Validate schema_version field — future-proof against config format changes

Path Expansion (src/lib/config.ts)

• Package paths come from user config and use tilde (~) expansion
• Validate expanded paths: directory exists, is absolute, doesn't traverse outside expected locations
• Never use user-supplied paths in require() or import() without validation
• Directory traversal risk: ../../etc/passwd in a path field should be caught and rejected