mcp

Personal Model Context Protocol servers, packaged as a uv workspace and Claude Code/Codex plugin marketplaces.

Every tool lives under packages/ as a workspace member with a single shared uv.lock. Each tool is also a self-installing plugin: a code generator (scripts/gen_marketplace.py) derives both marketplace indexes and the platform-specific plugin files from each package's metadata.

Packages

Fourteen tools ship as marketplace plugins. Two packages support them and are not plugins.

Each package has its own README with setup, tools, and usage. mcp-common and homeops-coordinator expose no MCP server and are excluded from the marketplace.

Related MCP server: Claude TypeScript MCP Servers

Installing a tool

Each packages/<tool>/ directory is the plugin source. When you install a plugin, Claude Code clones that directory into its plugin cache. On each session start, the plugin's hooks/install_deps.sh builds a persistent virtual environment (surviving plugin updates) and symlinks the tool's CLIs onto your PATH. There is no separate pip install step.

# Add this marketplace, then install a tool as a plugin
claude plugin marketplace add mrlesmithjr/mcp
claude plugin install unifi-tools@mrlesmithjr-mcp

Tools that need credentials (e.g. nextdns-tools, unifi-tools, ynab-tools) ship a configure command or document their config file; see the package README.

Every tool also generates a Codex plugin manifest (.codex-plugin/plugin.json) and installs cleanly via codex plugin marketplace add / codex plugin add. Codex uses an inline, plugin-root-relative MCP launcher (Codex does not expand ${CLAUDE_PLUGIN_ROOT} in a plugin's stdio argv the way Claude Code does) while Claude Code continues to use its existing .mcp.json definition. Verified end to end against a live codex exec session (issue #133).

Allow the tools in Claude Code: After installing any plugin, its MCP tools are deferred by default -- Claude Code does not pre-load their schemas, so they require an extra lookup step and are unlikely to be used automatically. Add each tool to permissions.allow in ~/.claude/settings.json. The tool namespace follows the pattern mcp__plugin_<slug>_<slug>__<tool_name>. Each package README lists the exact strings to add.

Layout

mcp/
├── pyproject.toml                  # Workspace root (virtual, non-distributable)
├── uv.lock                         # Single root lockfile
├── .python-version                 # Python floor (>=3.11)
├── packages/
│   ├── <tool>/                     # One directory per tool; this IS the plugin source
│   │   ├── pyproject.toml          # Package metadata (authoritative)
│   │   ├── .claude-plugin/
│   │   │   └── plugin.json          # GENERATED: Claude plugin metadata
│   │   ├── .codex-plugin/
│   │   │   └── plugin.json          # GENERATED: Codex plugin metadata
│   │   ├── .mcp.json                # GENERATED: Claude Code MCP definition
│   │   └── hooks/
│   │       ├── hooks.json           # GENERATED: SessionStart hook wiring
│   │       ├── install_deps.sh      # GENERATED: builds the persistent venv
│   │       └── run_server.sh        # GENERATED: cold-start launcher
│   ├── mcp-common/                  # Shared library (no plugin files)
│   └── homeops-coordinator/         # Daemon (no plugin files)
├── .claude-plugin/
│   └── marketplace.json             # GENERATED: Claude marketplace index
├── .agents/plugins/
│   └── marketplace.json             # GENERATED: Codex marketplace index
├── scripts/
│   ├── gen_marketplace.py           # Generates all plugin + marketplace files
│   └── install_launchagents.sh      # Manual LaunchAgent (re)install for dev
├── dev/
│   └── register_dev.py              # Registers <tool>-dev MCP servers for local dev
└── docs/
    └── migration.md                 # Per-tool subtree migration runbook

The six generated per-package files (the Claude and Codex plugin manifests, the shared MCP definition, and the three hook files) plus both marketplace indexes are produced by gen_marketplace.py. Do not hand-edit them. See CLAUDE.md for the full plugin-pattern details.

Developing

# Sync the workspace (installs all members + dev tools into .venv/)
# --all-packages is required for a virtual (non-package) workspace root
uv sync --all-packages

# Regenerate plugin + marketplace files after any pyproject change
uv run python scripts/gen_marketplace.py

# Verify generated files are up to date (CI check)
uv run python scripts/gen_marketplace.py --check

# Register dev-mode MCP servers (<tool>-dev, pointing at .venv/bin/)
uv run python dev/register_dev.py

Run tests per package, not in one combined invocation (test files share names across packages and collide when collected together):

uv run pytest packages/mcp-common
uv run pytest packages/weather-tools
uv run pytest packages/ynab-tools    # requires: uv sync --all-packages --extra dashboard

Adding a tool

Existing tools were migrated in from standalone repos via git subtree. To add another, follow the per-tool runbook in docs/migration.md.

Shared library

mcp-common (mrlesmithjr-mcp-common) is a dependency of every tool and is published separately to PyPI so plugins can resolve it when installed outside the workspace. See CLAUDE.md for the publish flow.