A collection of Model Context Protocol (MCP) servers, clients, and experiments for learning, prototyping, and comparing implementation styles across runtimes (Cloudflare Workers, Python, etc.).

1. Overview
2. Repository Structure
3. What is MCP?
4. Project Summaries
5. Quick Start
6. Development Environment
7. Contributing
8. Disclaimer

This monorepo hosts multiple MCP server and client implementations exploring different tooling stacks (Python + uv, TypeScript + Cloudflare Workers) and agent patterns (LLM-backed analysis, reactive agents, tool invocation). It is intended as a playground and reference.

MCP-dump/
├── ai-agent-postgres-mcp/        # AI agent using MCP to analyze a Postgres database
│   ├── ai_agent_postgres_mcp.ipynb
│   ├── main.py
│   └── README.md
├── mcp-hello/                    # Minimal MCP server (Cloudflare Workers / JS)
│   ├── src/
│   ├── test/
│   ├── package.json
│   └── README.md
├── mcp-files/                    # New Python MCP workspace (managed via uv)
│   ├── pyproject.toml            # Root Python project (workspace style)
│   ├── uv.lock
│   ├── examples/                 # Example Python clients & agents
│   │   └── clients/
│   │       ├── base.py
│   │       ├── gemini.py
│   │       └── react_agent.py
│   ├── mcp-server/               # Python MCP server implementation
│   │   ├── pyproject.toml
│   │   └── src/mcp_server/
│   │       ├── cli.py
│   │       ├── config.py
│   │       ├── helpers.py
│   │       ├── mcp.py
│   │       ├── tools.py
│   │       └── __init__.py
│   └── mcp-hello/                # (Experimental) parallel minimal example in Python
│       └── README.md
└── README.md

Note: mcp-files/mcp-hello is a Python-flavored minimal example separate from the root mcp-hello Cloudflare Workers implementation. They intentionally explore analogous concepts in different runtimes.

Model Context Protocol (MCP) standardizes how tools, agents, and large language models exchange contextual information, resources, and tool invocation results. It aims to:

• Provide predictable, typed exchanges
• Reduce ad-hoc prompt engineering glue
• Support richer, stateful multi-step agent behaviors

• ai-agent-postgres-mcp: Demonstrates connecting an AI agent to Postgres via MCP for conversational querying & analysis.
• mcp-hello (Cloudflare / Workers): Minimal TypeScript MCP server showcasing deployment in edge environments.
• mcp-files/mcp-server: A Python MCP server with tooling abstractions, CLI entrypoint, and strongly-typed helpers.
• mcp-files/examples/clients: Example Python clients (including a basic reactive agent pattern and Gemini integration placeholder).
• mcp-files/mcp-hello: Lightweight Python analogue of the Cloudflare example (experimental).

1. Enter the directory:

   cd mcp-hello

2. Install deps (pnpm / npm / yarn):

   npm install

3. Run tests:

   npm test

4. (Optional) Publish / dev with Wrangler:

   npx wrangler dev

This workspace uses uv for fast resolution & execution.

1. Navigate:

   cd mcp-files

2. Run the Python MCP server (CLI):

   uv run mcp-server

3. Try a client example (reactive agent):

   uv run examples/clients/react_agent.py

4. Explore available tools by invoking help:

   uv run mcp-server --help

Follow its local README.md for database connection setup. Typically you'll:

cd ai-agent-postgres-mcp
uv run main.py  # or python main.py depending on your environment

Recommended:

• Install uv for Python: https://docs.astral.sh/uv/
• Keep commits atomic (feature / chore / docs) using Conventional Commits.
• Use uv lock --upgrade when updating deps in Python workspace.

Contributions are welcome. Suggested contribution types:

• New MCP tool modules (mcp-files/mcp-server/src/mcp_server/tools.py)
• Additional runtime adapters (Rust, Go, etc.)
• Agent strategy examples (planning, retrieval-augmented, streaming)
• Documentation improvements & diagrams

Workflow:

1. Fork & branch from main.
2. Implement + add minimal docs/tests.
3. Run lint/tests (where applicable).
4. Open PR with clear description and rationale.

These implementations are experimental and not guaranteed production-grade. Security, robustness, and performance concerns may be intentionally simplified for clarity.

If you find this useful, feel free to open issues with questions or ideas for additional MCP experiment directions.