](https://mseep.ai/app/kaiohz-prospectio-api-mcp)
展望MCP API
一个基于FastAPI的应用程序，实现了用于潜在客户勘探的模型上下文协议（MCP）。该项目遵循清洁架构原则，在域、应用程序和基础设施层之间明确分离关注点。
该应用程序现在包括PostgreSQL和pgvector集成的持久存储功能，允许高效地存储和管理潜在客户数据。
🏗️ 项目架构
该项目实施 整洁架构 （也称为六边形架构），具有以下层：
- 领域层：核心业务实体和逻辑
- 应用层：用例和API路由
- 基础设施层：外部服务、API和框架实现
三相接触富集
该应用程序使用复杂的三阶段方法来丰富联系人，将专业信息发现、LinkedIn个人资料URL发现和传记信息收集分开：
第一阶段：困惑网络搜索（联系信息）
通过OpenRouter使用Perplexity的声纳模型查找专业联系信息：
- 名字：目标公司专业人员的全名
- 电子邮件地址：专业和工作电子邮件
- 电话号码：直接联系电话
- 各种职务名称：当前职位和角色
- 专业背景：职业信息
困惑搜索故意排除领英关键字，以避免低质量的领英搜索结果，而是专注于从各种专业来源查找经过验证的联系方式。
第二阶段：DuckDuckGo HTML搜索（领英网址）
在收集到联系信息后 DuckDuckGoClient 执行目标LinkedIn个人资料URL发现：
双重搜索策略：
- 主要搜索（姓名+公司）：搜索
site:linkedin.com/in "Person Name" "Company Name" - 后备搜索（标题+公司）：如果名称搜索没有结果，则返回
site:linkedin.com/in "Job Title" "Company Name"
主要特点：
- 速率限制以避免被阻塞（请求之间的可配置延迟）
- URL重复数据删除和规范化
- 基于正则表达式从HTML中提取LinkedIn个人资料URL
- 查询消毒以防止注射
第三阶段：困惑的网络搜索（联系人简历）
在发现LinkedIn网址后，二次困惑搜索会收集每个联系人的简历信息：
- 简短描述：联系人职业简介的简明摘要
- 完整简历：一本全面的传记，包括职业史、成就和专业背景
此阶段通过两个附加字段丰富了Contact实体：
short_description：简短的专业总结（显示在联系人列表中）full_bio：详细的履历信息（显示在联系人详细信息视图中）
配置选项
将这些环境变量添加到您的 .env 文件以自定义富集行为：
# Perplexity Web Search (Phase 1 & Phase 3)
WEB_SEARCH_MODEL=perplexity/sonar # Model for web search
WEB_SEARCH_TIMEOUT=60.0 # Request timeout in seconds
WEB_SEARCH_CONCURRENT_REQUESTS=5 # Max concurrent search requests
# DuckDuckGo LinkedIn Search (Phase 2)
DUCKDUCKGO_TIMEOUT=30.0 # Request timeout in seconds
DUCKDUCKGO_MAX_RESULTS=10 # Max LinkedIn URLs per search
DUCKDUCKGO_DELAY_BETWEEN_REQUESTS=2.0 # Rate limiting delay in seconds数据库迁移
如果您有一个现有的数据库，请运行以下迁移以添加生物列：
psql -d your_database -f /database/migrations/add_contact_bio_columns.sql或者直接执行SQL：
ALTER TABLE contacts ADD COLUMN IF NOT EXISTS short_description TEXT;
ALTER TABLE contacts ADD COLUMN IF NOT EXISTS full_bio TEXT;浓缩成分
| 组件 | 位置 | 目的 |
|---|---|---|
WebSearchClient | infrastructure/services/enrich_leads_agent/tools/web_search_client.py | 基于困惑的联系信息和生物搜索 |
DuckDuckGoClient | infrastructure/services/enrich_leads_agent/tools/duckduckgo_client.py | 通过HTML搜索发现LinkedIn URL |
DuckDuckGoConfig | config.py | DuckDuckGo设置的配置 |
WebSearchConfig | config.py | 困惑设置的配置 |
EnrichLeadsNodes | infrastructure/services/enrich_leads_agent/nodes.py | 协调三阶段的丰富 |
📁 项目结构
prospectio-api-mcp/
├── Dockerfile
├── README.md
├── curls/
│ └── list.http
├── database/
│ └── init.sql
├── docker-compose.yml
├── glama.json
├── poetry.lock
├── prospectio_api_mcp/
│ ├── __pycache__/
│ ├── application/
│ │ ├── api/
│ │ │ ├── leads_routes.py
│ │ │ ├── mcp_routes.py
│ │ │ ├── profile_routes.py
│ │ │ └── __pycache__/
│ │ └── use_cases/
│ │ ├── get_leads.py
│ │ ├── insert_leads.py
│ │ ├── profile.py
│ │ └── __pycache__/
│ ├── config.py
│ ├── domain/
│ │ ├── entities/
│ │ │ ├── company.py
│ │ │ ├── compatibility_score.py
│ │ │ ├── contact.py
│ │ │ ├── job.py
│ │ │ ├── leads.py
│ │ │ ├── leads_result.py
│ │ │ ├── profile.py
│ │ │ ├── work_experience.py
│ │ │ └── __pycache__/
│ │ ├── ports/
│ │ │ ├── compatibility_score.py
│ │ │ ├── fetch_leads.py
│ │ │ ├── leads_repository.py
│ │ │ ├── profile_respository.py
│ │ │ └── __pycache__/
│ │ ├── prompts/
│ │ │ └── compatibility_score.md
│ │ └── services/
│ │ ├── prompt_loader.py
│ │ ├── __pycache__/
│ │ └── leads/
│ │ ├── active_jobs_db.py
│ │ ├── jsearch.py
│ │ ├── mantiks.py
│ │ └── strategy.py
│ ├── infrastructure/
│ │ ├── api/
│ │ │ ├── client.py
│ │ │ ├── llm_client_factory.py
│ │ │ ├── llm_generic_client.py
│ │ │ └── __pycache__/
│ │ ├── dto/
│ │ │ ├── database/
│ │ │ ├── llm/
│ │ │ ├── mantiks/
│ │ │ └── rapidapi/
│ │ └── services/
│ │ ├── active_jobs_db.py
│ │ ├── compatibility_score.py
│ │ ├── jsearch.py
│ │ ├── leads_database.py
│ │ ├── mantiks.py
│ │ └── profile_database.py
│ ├── main.py
│ ├── mcp.py
│ ├── mcp_routes.py
│ └── __pycache__/
├── pyproject.toml
├── pyrightconfig.json
├── tests/
│ └── ut/
│ ├── test_1_profile_use_case.py
│ ├── test_active_jobs_db_use_case.py
│ ├── test_get_leads_use_case.py
│ ├── test_jsearch_use_case.py
│ ├── test_mantiks_use_case.py
│ └── __pycache__/
├── uv.lock🔧 核心组件
域层(prospectio_api_mcp/domain/)
实体
Contact(contact.py)：表示业务联系人（姓名、电子邮件、电话、职务、linkedin_url、short_description、full_bio）Company(company.py)：表示公司（名称、行业、规模、位置、描述）Job(job.py)：表示职位发布（职位、描述、地点、工资、要求）Leads(leads.py)：汇总公司、职位和联系人以获取潜在客户数据LeadsResult(leads_result.py)：表示导线插入操作的结果Profile(profile.py)：表示包含个人和专业信息的用户配置文件WorkExperience(work_experience.py)：表示配置文件的工作经验条目
港口
CompanyJobsPort(fetch_leads.py)：用于从任何数据源获取公司作业的抽象接口
- fetch_company_jobs(location: str, job_title: list[str]) -> Leads：求职的抽象方法
LeadsRepositoryPort(leads_repository.py)：用于持久化潜在客户数据的抽象接口
- save_leads(leads: Leads) -> None：抽象的存储方法
ProfileRepositoryPort(profile_respository.py)：用于配置文件数据管理的抽象接口
- 与配置文件相关的存储库操作
战略(prospectio_api_mcp/domain/services/leads/)
CompanyJobsStrategy(strategy.py)：作业检索策略的抽象基类- 具体策略：每个数据源的实现：
- ActiveJobsDBStrategy, JsearchStrategy, MantiksStrategy
应用层(prospectio_api_mcp/application/)
APIprospectio_api_mcp/application/api/)
leads_routes.py：定义用于潜在客户管理的FastAPI端点profile_routes.py：定义用于配置文件管理的FastAPI端点
使用案例(prospectio_api_mcp/application/use_cases/)
InsertCompanyJobsUseCase(insert_leads.py)：协调从不同来源检索和插入公司作业的过程
- 接受策略和存储库，检索潜在客户并将其持久化到数据库中
GetLeadsUseCase(get_leads.py)：处理潜在客户数据的检索ProfileUseCase(profile.py)：管理与配置文件相关的操作
基础设施层(prospectio_api_mcp/infrastructure/)
API客户端(prospectio_api_mcp/infrastructure/api/client.py)
BaseApiClient：外部API调用的异步HTTP客户端
DTO(prospectio_api_mcp/infrastructure/dto/)
- 数据库DTO:
base.py,company.py,job.py,contact.py,profile.py,work_experience.py-SQLAlchemy持久化模型 - 曼蒂克斯DTO！:
company.py,company_response.py,job.py,location.py,salary.py-Mantiks API的数据传输对象 - Rapidapi DTOS:
active_jobs_db.py,jsearch.py-RapidAPI服务的数据传输对象
服务项目(prospectio_api_mcp/infrastructure/services/)
ActiveJobsDBAPI：活动作业DB API适配器JsearchAPI：Jsearch API的适配器MantiksAPI：Mantiks API适配器LeadsDatabase：用于潜在客户持久化的PostgreSQL存储库实现ProfileDatabase：用于配置文件管理的PostgreSQL存储库实现
所有API服务都实现 CompanyJobsPort 接口，数据库服务实现 LeadsRepositoryPort 接口，允许轻松交换和扩展。
🚀 应用程序入口点(prospectio_api_mcp/main.py)
FastAPI应用程序配置为：
- 管理应用程序生命周期：处理启动和关闭事件，包括MCP会话生命周期。
- 公开多种协议:
- REST API可在 /rest/v1/ - MCP协议可在 /prospectio/ （实施于 mcp_routes.py)
- 集成路由器：包括通过FastAPI的APIRouter进行全面的潜在客户和个人资料管理的潜在客户插入路线和个人资料路线。
- 加载配置：从加载基于环境的设置
config.py使用Pydantic。 - 依赖注入：将服务实现、策略和存储库注入端点以实现干净的分离。
- 数据库集成：配置PostgreSQL连接以持久存储潜在客户数据和配置文件。
⚙️ 配置
要运行应用程序，您需要配置环境变量。这是通过使用 .env 项目根目录下的文件。
- 创建
.env文件:
复制示例文件 .env.example 到名为的新文件 .env.
cp .env.example .env
cp .env .env.docker- 编辑
.env文件:
打开 .env 文件并填写以下变量的所需值：
- EXPOSE: stdio 或 http - MASTER_KEY：你的万能钥匙。 - ALLOWED_ORIGINS：以逗号分隔的允许来源列表。 - MANTIKS_API_URL：Mantiks API的基本URL。 - MANTIKS_API_KEY：您的API Mantiks密钥。 - RAPIDAPI_API_KEY：RapidAPI的API密钥。 - JSEARCH_API_URL：Jsearch API的基本URL。 - ACTIVE_JOBS_DB_URL：活动作业数据库API的基本URL。 - DATABASE_URLPostgreSQL连接字符串（例如。， postgresql+asyncpg://user:password@host:port/database)
应用程序使用Pydantic Settings从 .env 文件（参见 prospectio_api_mcp/config.py).
📦 依赖关系(pyproject.toml)
核心依赖关系
- 快速API（0.115.14）：具有自动API文档的现代web框架
- MCP（1.10.1）：模型上下文协议实现
- Pydantic（2.10.3）：数据验证和序列化
- HTTPX（0.28.1）：用于外部API调用的HTTP客户端
- SQL炼金术（2.0.41）：用于PostgreSQL集成的数据库ORM
- asyncpg（0.30.0）：异步PostgreSQL驱动程序
- psycopg（3.2.4）：PostgreSQL适配器
发展依赖性
- Pytest：测试框架
🔄 数据流
- HTTP请求：客户端向以下对象发出POST请求
/rest/v1/insert/leads/{source}JSON正文包含位置和job_title参数。 - 路由处理程序：FastAPI路由
application/api/routes.py接收请求并提取参数。 - 战略地图：处理器选择适当的策略（例如。，
ActiveJobsDBStrategy,JsearchStrategy等等）。 - 用例执行:
InsertCompanyJobsUseCase使用所选策略和存储库进行实例化。 - 战略执行：用例委托给战略
execute()获取潜在客户数据的方法。 - 港口执行：该战略称港口为
fetch_company_jobs(location, job_title)该方法由基础设施适配器实现（例如。，ActiveJobsDBAPI).
🧪 测试
该项目包括遵循pytest最佳实践和清洁架构原则的全面单元测试。测试位于 tests/ 目录，并使用依赖注入来模拟外部服务。
测试结构
tests/
└── ut/ # Unit tests
├── test_mantiks_use_case.py # Mantiks strategy tests
├── test_jsearch_use_case.py # JSearch strategy tests
├── test_active_jobs_db_use_case.py # Active Jobs DB strategy tests
├── test_get_leads.py # Get leads use case tests
└── test_profile.py # Profile use case tests运行测试
安装依赖关系：
poetry install运行所有测试：
# Run all tests
poetry run pytest
# Run with verbose output
poetry run pytest -v运行特定测试文件：
# Run Mantiks tests only
poetry run pytest tests/ut/test_mantiks_use_case.py -v
# Run JSearch tests only
poetry run pytest tests/ut/test_jsearch_use_case.py -v
# Run Active Jobs DB tests only
poetry run pytest tests/ut/test_active_jobs_db_use_case.py -v
# Run Get Leads tests only
poetry run pytest tests/ut/test_get_leads.py -v
# Run Profile tests only
poetry run pytest tests/ut/test_profile.py -v运行特定测试方法：
# Run a specific test method
poetry run pytest tests/ut/test_mantiks_use_case.py::TestMantiksUseCase::test_get_leads_success -v测试环境变量
测试需要 .env 配置文件。复制示例文件：
cp .env.example .envCI管道自动处理环境设置和数据库初始化。
🏃♂️ 运行应用程序
在运行应用程序之前，请确保您已按照中所述设置了环境变量 配置 部分。
方案1：地方发展
- 安装依赖项:
poetry install- 运行应用程序:
poetry run fastapi run prospectio_api_mcp/main.py --reload --port 选项2：Docker Compose（推荐）
Docker Compose设置包括应用程序和带有pgvector扩展的PostgreSQL数据库。
首先建立一个勘探网络：
docker network create prospectio- 使用Docker Compose构建和运行:
# Build and start the container
docker-compose up --build
# Or run in background (detached mode)
docker-compose up -d --build- 停止应用程序:
# Stop the container
docker-compose down
# Stop and remove volumes (if needed)
docker-compose down -v- 查看日志:
# View real-time logs
docker-compose logs -f
# View logs for specific service
docker-compose logs -f prospectio-api-mcp
### Accessing the APIs
Once the application is running (locally or via Docker), you can access:
- **REST API**: `http://localhost:/rest/v1/insert/leads/{source}`
- `source` can be: mantiks, active_jobs_db, jsearch
- Method: POST with JSON body containing `location` and `job_title` array
- Example: `http://localhost:/rest/v1/insert/leads/mantiks`
- **API Documentation**: `http://localhost:/docs`
- **MCP Endpoint**: `http://localhost:/prospectio/mcp/sse`
# Add to claude
change settings json to match your environment
{ "mcpServers": { "Prospectio-stdio": { "command": "/uv", "args": [ "--directory", " ", "run", "prospectio_api_mcp/main.py" ] } } }
# 添加到Gemini cli
更改json设置以匹配您的环境
{ "mcpServers": { "prospectio-http": { "httpUrl": "http://localhost:/prospectio/mcp/sse", "timeout": 30000 }, "Prospectio-stdio": { "command": "/uv", "args": [ "--directory", " ", "run", "prospectio_api_mcp/main.py" ] } } }
**建于❤️ Prospectio团队**