生产力工具 MCP 服务集合

Puddles

A collection of Model Context Protocol (MCP) servers for productivity tools. These servers enable AI assistants like Claude to interact with your productivity apps.

Servers

Quick Start

Each server is self-contained with its own dependencies and setup instructions. See the individual server READMEs for details.

Gmail MCP

cd servers/gmail-mcp
python -m venv .venv
source .venv/bin/activate
pip install -e .

See servers/gmail-mcp/README.md for full setup instructions including Google OAuth configuration.

Configuring Claude

After installing a server, configure Claude to use it.

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "gmail-mcp": {
      "command": "/path/to/puddles/servers/gmail-mcp/.venv/bin/python",
      "args": ["-m", "gmail_mcp"]
    }
  }
}

Restart Claude Desktop after saving.

Claude Code (VS Code / CLI)

Edit ~/.claude/claude.json:

{
  "mcpServers": {
    "gmail-mcp": {
      "command": "/path/to/puddles/servers/gmail-mcp/.venv/bin/python",
      "args": ["-m", "gmail_mcp"]
    }
  }
}

Finding Your Path

Run this from a server directory to get the exact Python path:

echo "$(pwd)/.venv/bin/python"

Architecture

puddles/
├── packages/
│   └── mcp-hooks/          # TypeScript security hooks library (egress + ingress)
├── openclaw-plugins/       # OpenClaw plugins consuming mcp-hooks
├── servers/
│   └── gmail-mcp/          # Gmail MCP server (Python, self-contained)
│       ├── .venv/          # Server-specific virtual environment
│       ├── pyproject.toml  # Server dependencies
│       ├── src/            # Server source code
│       ├── tests/          # Server tests
│       └── docs/           # Server documentation
├── scripts/
│   └── mac-mini/           # Host scripts for the Mac Mini server
├── docs/
│   ├── plans/              # Pending plans; completed work in completed/
│   └── openclaw-setup/     # Mac Mini setup guides
└── .github/
    └── copilot-instructions.md  # Development guidelines

Two ecosystems coexist:

• Python servers (servers/) — each MCP server is fully self-contained with its own pyproject.toml and virtualenv. Install per-server.
• TypeScript packages + plugins (packages/, openclaw-plugins/) — managed as a pnpm workspace. Run pnpm install at the repo root to bootstrap; plugins reference packages/mcp-hooks via "workspace:*".

Adding a New Server

1. Create a new directory under servers/
2. Add pyproject.toml, src/, tests/, and README.md
3. Create a virtual environment: python -m venv .venv
4. Add the server to the table above

Adding a New OpenClaw Plugin

See openclaw-plugins/README.md for plugin conventions. New plugins are picked up automatically by pnpm install via the openclaw-plugins/* workspace glob.

Development

Start with AGENTS.md, a tracked symlink to the shared development instructions. The safe feature development skill defines design approval, isolated worktrees, the fast local and DEV loop, independent review, and delivery through production. The managed runner guide supplies current commands.

The development loop manager skill guides an agent reviewing recent development loops for late failures, slow feedback, repeated work, and disk growth. It turns findings into maintained improvements and checks whether later loops benefit.

The security architecture defines trust rings and boundaries across agents, host services, and delivery, with implementation references and known gaps.

License

MIT