karoldavid/mcp-ai-powered-data-injection

MCP AI-Powered Data Injection

MCP server wrapping a FastAPI service for AI-powered data injection into PostgreSQL. Enables AI agents (like Claude) to understand schemas, insert test data, and validate results.

Capabilities

• Schema inspection - Task table structure and validation rules
• Data insertion - Bulk task creation and synthetic data generation
• Summary analytics - Aggregate statistics and counts
• MCP integration - Full Model Context Protocol support via stdio

🤖 Claude Desktop Integration

Ready to use with Claude Desktop! This project includes complete MCP server integration with documented setup and testing evidence.

• 📋 Setup Guide: See for step-by-step Claude Desktop configuration
• ✅ Integration Evidence: See for screenshots and test results of 1000+ task generation

Quick Test: After setup, ask Claude: "Use get_schema to show me the task structure, then generate 10 sample tasks"

Fast Start (Docker Only)

git clone <repo-url>
cd mcp-ai-powered-data-injection
docker-compose up -d --build
# Wait for postgres healthy then app available at http://localhost:8000
# (Optional) MCP proxy container will also start (service name: mcp)
docker-compose logs -f mcp

Check health:

curl -s localhost:8000/mcp/health

Important: The mcp service in Docker is for experimentation/logging only. Claude Desktop cannot connect to an MCP server that runs inside a container via stdio; it spawns a local process and communicates through pipes. For Claude integration you must run mcp_server_http.py directly on your host (macOS) with MCP_API_BASE pointing to the Docker-exposed FastAPI (http://localhost:8000).

Endpoints Cheat Sheet

Example Insert

curl -X POST localhost:8000/mcp/tasks \
  -H 'Content-Type: application/json' \
  -d '[{"title":"Example","status":"pending","priority":"medium"}]'

Example Summary

Example Deterministic Generation (defaults to 50 tasks)

curl -s -X POST localhost:8000/mcp/tasks/generate \
  -H 'Content-Type: application/json' \
  -d '{}' | jq

Custom count + tags:

curl -s -X POST localhost:8000/mcp/tasks/generate \
  -H 'Content-Type: application/json' \
  -d '{"count":15, "tags":["synthetic","demo"]}' | jq

Then re-check summary:

curl -s localhost:8000/mcp/tasks/summary | jq

Local Dev (Optional, without Docker app container)

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Using Python 3.13 (Experimental Upgrade)

If you have Python 3.13 installed (e.g. via Homebrew or pyenv), you can create an alternate virtual environment:

brew install python@3.13          # macOS (if not already installed)
python3.13 -m venv .venv-py313
source .venv-py313/bin/activate
pip install -r requirements.txt
python mcp_server_http.py

Update Claude config to point to .venv-py313/bin/python if you switch interpreters.

Docker image now uses python:3.13-slim for better wheel support (vs alpine). If you encounter build issues for binary packages, ensure build tools are installed or fall back to python:3.13-alpine only when all dependencies provide musl wheels. docker-compose up -d postgres # if only DB needed uvicorn app.main:app --reload

Run MCP proxy locally (outside docker)

export MCP_API_BASE=http://localhost:8000
python mcp_server_http.py

Claude Desktop Integration

Example Claude Desktop mcp server definition:

{
  "mcpServers": {
    "tasks": {
      "command": "/Users/youruser/git/private/mcp-ai-powered-data-injection/scripts/run_mcp.sh",
      "args": [],
      "env": {
        "MCP_API_BASE": "http://localhost:8000",
        "MCP_HTTP_TIMEOUT": "30"
      }
    }
  }
}

On launch Claude will discover tools (list_tools), then you can ask it for e.g.:

• "Call the generate_tasks MCP tool to create 10 tasks tagged demo"
• "Insert these tasks via insert_tasks" (paste array)
• "Fetch the task schema"
• "Summarize current tasks using get_summary"

Available MCP Tools (stdio server)

Arguments are validated lightly; for full field definitions call get_schema first.

Testing with MCP Client Script

For development and testing, use the included scripts/mcp_client.py to interact with your MCP server directly:

# Ensure your environment is set up
source .venv/bin/activate
export MCP_API_BASE=http://localhost:8000

# Start the MCP server in one terminal
python mcp_server_http.py

# In another terminal, test the client
python scripts/mcp_client.py list                    # List available tools
python scripts/mcp_client.py call get_health         # Check server health
python scripts/mcp_client.py call get_summary        # Get task statistics

# Insert tasks with JSON data
python scripts/mcp_client.py call insert_tasks --data '[{"title":"Test Task","description":"Testing via client","status":"pending","priority":"high"}]'

# Generate synthetic tasks
python scripts/mcp_client.py call generate_tasks --data '{"count":5,"tags":["test","demo"]}'

# Send raw JSON-RPC for advanced testing
python scripts/mcp_client.py raw '{"jsonrpc":"2.0","id":99,"method":"tools/list"}'

The client automatically handles MCP protocol initialization and pretty-prints responses, making it ideal for development workflow testing.

Adjust DB via env (defaults align with compose app service):

TASK_DB_HOST=localhost
TASK_DB_PORT=5433
TASK_DB_NAME=task_manager
TASK_DB_USER=task_user
TASK_DB_PASSWORD=task_password

Stopping

docker-compose down            # keep data
docker-compose down -v         # delete data volume

Tech Stack

FastAPI, SQLAlchemy 2.x, psycopg3, PostgreSQL 15, Docker Compose.

Security Note

Database credentials are baked as environment variables for convenience (Dev Environment). For production, move secrets to compose .env files or secret managers.

Troubleshooting Claude Desktop MCP Connection

Minimal Manual Handshake Test

You can simulate a client:

python mcp_server_http.py <<'EOF'
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"manual","version":"1.0"}}}
EOF

Expect an initialize result JSON. (Ctrl+C to stop server otherwise it idles.)

Recommended Local Setup Script

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
docker compose up -d --build app   # starts postgres + app
export MCP_API_BASE=http://localhost:8000
python mcp_server_http.py

If successful you will see [DEBUG] API_BASE=http://localhost:8000 printed to stderr.