Handles environment-based configuration, automatically finding and loading .env files
Serves as the foundation framework for the MCP API, providing the REST endpoints and routing capabilities
Used for dependency management and packaging of the MCP server
Provides data validation and serialization for the lead prospecting API
Used as the testing framework for the MCP server
Prospectio MCP API
A FastAPI-based application that implements the Model Context Protocol (MCP) for lead prospecting. The project follows Clean Architecture principles with a clear separation of concerns across domain, application, and infrastructure layers.
The application now includes persistent storage capabilities with PostgreSQL and pgvector integration, allowing leads data to be stored and managed efficiently.
🏗️ Project Architecture
This project implements Clean Architecture (also known as Hexagonal Architecture) with the following layers:
- Domain Layer: Core business entities and logic
- Application Layer: Use cases and API routes
- Infrastructure Layer: External services, APIs, and framework implementations
📁 Project Structure
🔧 Core Components
Domain Layer (prospectio_api_mcp/domain/
)
Entities
Contact
(contact.py
): Represents a business contact (name, email, phone, title)Company
(company.py
): Represents a company (name, industry, size, location, description)Job
(job.py
): Represents a job posting (title, description, location, salary, requirements)Leads
(leads.py
): Aggregates companies, jobs, and contacts for lead dataLeadsResult
(leads_result.py
): Represents the result of a lead insertion operationProfile
(profile.py
): Represents a user profile with personal and professional informationWorkExperience
(work_experience.py
): Represents work experience entries for a profile
Ports
CompanyJobsPort
(fetch_leads.py
): Abstract interface for fetching company jobs from any data sourcefetch_company_jobs(location: str, job_title: list[str]) -> Leads
: Abstract method for job search
LeadsRepositoryPort
(leads_repository.py
): Abstract interface for persisting leads datasave_leads(leads: Leads) -> None
: Abstract method for saving leads to storage
ProfileRepositoryPort
(profile_respository.py
): Abstract interface for profile data management- Profile-related repository operations
Strategies (prospectio_api_mcp/domain/services/leads/
)
CompanyJobsStrategy
(strategy.py
): Abstract base class for job retrieval strategies- Concrete Strategies: Implementations for each data source:
ActiveJobsDBStrategy
,JsearchStrategy
,MantiksStrategy
Application Layer (prospectio_api_mcp/application/
)
API (prospectio_api_mcp/application/api/
)
leads_routes.py
: Defines FastAPI endpoints for leads managementprofile_routes.py
: Defines FastAPI endpoints for profile management
Use Cases (prospectio_api_mcp/application/use_cases/
)
InsertCompanyJobsUseCase
(insert_leads.py
): Orchestrates the process of retrieving and inserting company jobs from different sources- Accepts a strategy and repository, retrieves leads and persists them to the database
GetLeadsUseCase
(get_leads.py
): Handles retrieval of leads dataProfileUseCase
(profile.py
): Manages profile-related operations
Infrastructure Layer (prospectio_api_mcp/infrastructure/
)
API Client (prospectio_api_mcp/infrastructure/api/client.py
)
BaseApiClient
: Async HTTP client for external API calls
DTOs (prospectio_api_mcp/infrastructure/dto/
)
- Database DTOs:
base.py
,company.py
,job.py
,contact.py
,profile.py
,work_experience.py
- SQLAlchemy models for persistence - Mantiks DTOs:
company.py
,company_response.py
,job.py
,location.py
,salary.py
- Data transfer objects for Mantiks API - RapidAPI DTOs:
active_jobs_db.py
,jsearch.py
- Data transfer objects for RapidAPI services
Services (prospectio_api_mcp/infrastructure/services/
)
ActiveJobsDBAPI
: Adapter for Active Jobs DB APIJsearchAPI
: Adapter for Jsearch APIMantiksAPI
: Adapter for Mantiks APILeadsDatabase
: PostgreSQL repository implementation for leads persistenceProfileDatabase
: PostgreSQL repository implementation for profile management
All API services implement the CompanyJobsPort
interface, and the database service implements the LeadsRepositoryPort
interface, allowing for easy swapping and extension.
🚀 Application Entry Point (prospectio_api_mcp/main.py
)
The FastAPI application is configured to:
- Manage Application Lifespan: Handles startup and shutdown events, including MCP session lifecycle.
- Expose Multiple Protocols:
- REST API available at
/rest/v1/
- MCP protocol available at
/prospectio/
(implemented inmcp_routes.py
)
- REST API available at
- Integrate Routers: Includes leads insertion routes and profile routes for comprehensive lead and profile management via FastAPI's APIRouter.
- Load Configuration: Loads environment-based settings from
config.py
using Pydantic. - Dependency Injection: Injects service implementations, strategies, and repository into endpoints for clean separation.
- Database Integration: Configures PostgreSQL connection for persistent storage of leads data and profiles.
⚙️ Configuration
To run the application, you need to configure your environment variables. This is done using a .env
file at the root of the project.
- Create the
.env
file: Copy the example file.env.example
to a new file named.env
. - Edit the
.env
file: Open the.env
file and fill in the required values for the following variables:EXPOSE
:stdio
orhttp
MASTER_KEY
: Your master key.ALLOWED_ORIGINS
: Comma-separated list of allowed origins.MANTIKS_API_URL
: The base URL for the Mantiks API.MANTIKS_API_KEY
: Your API key for Mantiks.RAPIDAPI_API_KEY
: Your API key for RapidAPI.JSEARCH_API_URL
: The base URL for the Jsearch API.ACTIVE_JOBS_DB_URL
: The base URL for the Active Jobs DB API.DATABASE_URL
: PostgreSQL connection string (e.g.,postgresql+asyncpg://user:password@host:port/database
)
The application uses Pydantic Settings to load these variables from the .env
file (see prospectio_api_mcp/config.py
).
📦 Dependencies (pyproject.toml
)
Core Dependencies
- FastAPI (0.115.14): Modern web framework with automatic API documentation
- MCP (1.10.1): Model Context Protocol implementation
- Pydantic (2.10.3): Data validation and serialization
- HTTPX (0.28.1): HTTP client for external API calls
- SQLAlchemy (2.0.41): Database ORM for PostgreSQL integration
- asyncpg (0.30.0): Async PostgreSQL driver
- psycopg (3.2.4): PostgreSQL adapter
Development Dependencies
- Pytest: Testing framework
🔄 Data Flow
- HTTP Request: Client makes a POST request to
/rest/v1/insert/leads/{source}
with JSON body containing location and job_title parameters. - Route Handler: The FastAPI route in
application/api/routes.py
receives the request and extracts parameters. - Strategy Mapping: The handler selects the appropriate strategy (e.g.,
ActiveJobsDBStrategy
,JsearchStrategy
, etc.) based on the source. - Use Case Execution:
InsertCompanyJobsUseCase
is instantiated with the selected strategy and repository. - Strategy Execution: The use case delegates to the strategy's
execute()
method to fetch leads data. - Port Execution: The strategy calls the port's
fetch_company_jobs(location, job_title)
method, which is implemented by the infrastructure adapter (e.g.,ActiveJobsDBAPI
).
🧪 Testing
The project includes comprehensive unit tests following pytest best practices and Clean Architecture principles. Tests are located in the tests/
directory and use dependency injection for mocking external services.
Test Structure
Running Tests
Install Dependencies:
Run All Tests:
Run Specific Test Files:
Run Specific Test Methods:
Environment Variables for Testing
Tests require a .env
file for configuration. Copy the example file:
The CI pipeline automatically handles environment setup and database initialization.
🏃♂️ Running the Application
Before running the application, make sure you have set up your environment variables as described in the Configuration section.
Option 1: Local Development
- Install Dependencies:
- Run the Application:
Option 2: Docker Compose (Recommended)
The Docker Compose setup includes both the application and PostgreSQL database with pgvector extension.
- Build and Run with Docker Compose:
- Stop the Application:
- View Logs:
Jsearch (RapidAPI):
Local REST API:
MCP SSE Endpoint:
Add to claude
change settings json to match your environment
Add to Gemini cli
change settings json to match your environment
This server cannot be installed
remote-capable server
The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.
A FastAPI-based application that implements the Model Context Protocol for lead prospecting, allowing users to retrieve business leads from different data sources like Mantiks through a clean architecture.
Related MCP Servers
- -securityAlicense-qualityA high-performance FastAPI server supporting Model Context Protocol (MCP) for seamless integration with Large Language Models, featuring REST, GraphQL, and WebSocket APIs, along with real-time monitoring and vector search capabilities.Last updated -5PythonMIT License
- -securityFlicense-qualityA FastAPI-based implementation of the Model Context Protocol that enables standardized interaction between AI models and development environments, making it easier for developers to integrate and manage AI tasks.Last updated -5PythonMIT License
- -securityFlicense-qualityA simple application demonstrating Model Context Protocol (MCP) integration with FastAPI and Streamlit, allowing users to interact with LLMs through a clean interface.Last updated -3Python
- -securityFlicense-qualityA Model Context Protocol (MCP) service that enables integration with Mantis Bug Tracker, allowing users to query and analyze bug tracking data through natural language commands.Last updated -925TypeScript