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.
🏗️ 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, ports (interfaces), and strategies
- Infrastructure Layer: External services, APIs, and framework implementations
📁 Project Structure
🔧 Core Components
Domain Layer (src/domain/
)
Entities (src/domain/entities/leads.py
)
Contact
: Represents a business contact with name, email, and phoneCompany
: Represents a company with name, industry, size, and locationLeads
: Aggregates companies and contacts for lead data
Application Layer (src/application/
)
Ports (src/application/ports/leads/get_leads.py
)
ProspectAPIPort
: Abstract interface defining the contract for prospect data sourcesfetch_leads()
: Abstract method for fetching lead data
Use Cases (src/application/use_cases/leads/get_leads.py
)
GetLeadsContactsUseCase
: Orchestrates the process of getting leads from different sources- Accepts a source identifier and a port implementation
- Uses strategy pattern to delegate to appropriate strategy based on source
Strategies (src/application/strategies/leads/
)
GetLeadsStrategy
: Abstract base class for lead retrieval strategiesMantiksStrategy
: Concrete implementation for Mantiks data source- Delegates to the injected port to fetch leads
Infrastructure Layer (src/infrastructure/
)
API Routes (src/infrastructure/api/prospect_routes.py
)
- FastAPI Router: RESTful API endpoints
- MCP Integration: Model Context Protocol tools registration
get_leads(source: str)
: Endpoint that accepts a source parameter and returns lead data- Maps source to appropriate service implementation
- Handles error cases with proper HTTP status codes
Services (src/infrastructure/services/mantiks.py
)
MantiksAPI
: Concrete implementation ofProspectAPIPort
- Currently returns mock data for development/testing
- Can be extended to integrate with actual Mantiks API
🚀 Application Entry Point (src/main.py
)
The FastAPI application is configured with:
- Lifespan Management: Properly manages MCP session lifecycle
- Dual Protocol Support:
- REST API at
/rest/v1/
- MCP protocol at
/prospectio/
- REST API at
- Router Integration: Includes prospect routes for lead management
⚙️ Configuration (src/config.py
)
Environment-based configuration using Pydantic Settings:
Config
: General application settings (MASTER_KEY, ALLOWED_ORIGINS)MantiksConfig
: Mantiks API-specific settings (API_BASE, API_KEY)- Environment Loading: Automatically finds and loads
.env
files
📦 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
Development Dependencies
- Pytest: Testing framework
🔄 Data Flow
- HTTP Request: Client makes request to
/rest/v1/leads/{source}
- Route Handler:
get_leads()
function receives source parameter - Service Mapping: Source is mapped to appropriate service (e.g., MantiksAPI)
- Use Case Execution:
GetLeadsContactsUseCase
is instantiated with source and service - Strategy Selection: Use case selects appropriate strategy based on source
- Port Execution: Strategy calls the port's
fetch_leads()
method - Data Return: Lead data is returned through the layers back to client
🎯 Design Patterns
1. Clean Architecture
- Clear separation of concerns
- Dependency inversion (infrastructure depends on application, not vice versa)
2. Strategy Pattern
- Different strategies for different lead sources
- Easy to add new lead sources without modifying existing code
3. Port-Adapter Pattern (Hexagonal Architecture)
- Ports define interfaces for external dependencies
- Adapters implement these interfaces for specific technologies
4. Dependency Injection
- Services are injected into use cases
- Promotes testability and flexibility
🔧 Extensibility
Adding New Lead Sources
- Create new service class implementing
ProspectAPIPort
ininfrastructure/services/
- Add new strategy class extending
GetLeadsStrategy
inapplication/strategies/leads/
- Register the new strategy in
GetLeadsContactsUseCase.strategies
dictionary - Add service mapping in
prospect_routes.py
Adding New Endpoints
- Add new routes in
infrastructure/api/
directory - Create corresponding use cases in
application/use_cases/
- Define new ports if external integrations are needed
🏃♂️ Running the Application
- Install Dependencies:
- Set Environment Variables:
Create a
.env
file with required configuration - Run the Application:
- Access APIs:
- REST API:
http://localhost:8000/rest/v1/leads/mantiks
- API Documentation:
http://localhost:8000/docs
- MCP Endpoint:
http://localhost:8000/prospectio/mcp/sse
- REST API:
🧪 Testing
The project structure supports easy testing:
- Unit Tests: Test individual components in isolation
- Integration Tests: Test the interaction between layers
- Mock Services: Use mock implementations for external dependencies
📝 License
Apache 2.0 License
👥 Author
Yohan Goncalves yohan.goncalves.pro@gmail.com
This server cannot be installed
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