prospectio-api

This MCP server exposes two primary interfaces. First, a REST API under /rest/v1/ for standard CRUD and report operations related to leads and profiles. Second, the MCP protocol endpoint under /prospectio/ enables Model Context Protocol interactions for programmatic lead prospecting, where MCP clients can request lead data, profiles, and related context. The application is built with FastAPI and follows Clean Architecture, separating domain, application, and infrastructure concerns. To begin, ensure your environment is configured (see installation steps) and start the server; you will be able to insert and retrieve leads via use cases, as well as manage profiles. The server integrates with PostgreSQL for persistent storage and supports vector-enabled data through pgvector for efficient similarity and matching operations. When running, consider using a client that speaks MCP to fetch leads, insert results, or query profiles as part of a multi-source prospecting workflow.

Prerequisites:

• Python 3.11+ installed on your machine or server
• PostgreSQL database available and reachable
• git installed to clone the repository

1. Clone the repository

• git clone https://github.com/your-org/prospectio-api-mcp.git
• cd prospectio-api-mcp

2. Create and configure a virtual environment

• python -m venv venv
• source venv/bin/activate # On Windows: venv\Scripts\activate

3. Install Python dependencies

• pip install -U pip setuptools wheel
• pip install -r pyproject.toml # If using Poetry, install via Poetry as below

4. Install via Poetry (recommended for this project)

• curl -sSL https://install.python-poetry.org | python3 -
• poetry install

5. Configure environment

• Copy example env and tailor database settings
  • cp .env.example .env
  • edit .env to include DATABASE_URL or components (host, port, user, password, dbname)

6. Prepare the database

• (Optional) Run any provided initialization scripts
• Create PostgreSQL database and enable pgvector extension if needed

7. Run the server

• poetry run python -m prospectio_api_mcp.main
• Or if not using Poetry: python -m prospectio_api_mcp.main

8. Verify the server

• Access REST API at http://localhost:8000/rest/v1/
• Access MCP endpoint at http://localhost:8000/prospectio/

Tips and common considerations:

• Ensure the .env or environment variables provide a valid PostgreSQL connection string (DATABASE_URL) or individual components (DATABASE_HOST, DATABASE_PORT, etc.).
• The server uses FastAPI with a Clean Architecture layout; dependencies are injected per endpoint, making it straightforward to swap data sources or storage implementations via the Ports/Adapters pattern.
• If you enable advanced features, you may want to preload leads or profiles during startup for faster MCP responses.
• For production, consider running behind a reverse proxy (e.g., Nginx) and enabling TLS. Monitor logs with the LOG_LEVEL setting and consider configuring a proper WSGI/ASGI server stack (e.g., uvicorn with Gunicorn) for production deployments.
• When debugging, check the PostgreSQL schema in database/init.sql and ensure the required tables exist before inserting leads.