# construction-mcp-server

**Repository Path**: handaas/construction-mcp-server

## Basic Information

- **Project Name**: construction-mcp-server
- **Description**: HandaaS 建筑报建 MCP Server — 企业搜索/企业工程项目/项目搜索/项目详情/招投标/合同/施工许可/竣工信息
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-21
- **Last Updated**: 2026-10-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 建筑报建全流程监控

[该MCP服务提供企业关键词搜索、企业建筑工程项目明细、建筑项目搜索、项目详情、招投标、合同、施工图审查、施工许可和竣工信息查询功能。](https://www.handaas.com/)


## 主要功能

- 🔍 企业简称与关键词搜索
- 🏢 企业建筑工程项目明细查询
- 🏗️ 建筑报建项目搜索
- 🏢 项目基本信息和参建主体查询
- 📢 项目招投标信息查询
- 📝 项目合同信息查询
- 📐 施工图审查信息查询
- 🏭 施工许可信息查询
- ✅ 竣工备案和验收信息查询

## 环境要求

- Python 3.10+
- 依赖包：python-dotenv, requests, mcp

## 本地快速启动

### 1. 克隆项目
```bash
git clone https://github.com/handaas/construction-mcp-server
cd construction-mcp-server
```

### 2. 创建虚拟环境&安装依赖

```bash
python -m venv mcp_env && source mcp_env/bin/activate
pip install -r requirements.txt
```

### 3. 环境配置

复制环境变量模板并配置：

```bash
cp .env.example .env
```

编辑 `.env` 文件，配置以下环境变量：

```env
INTEGRATOR_ID=your_integrator_id
SECRET_ID=your_secret_id
SECRET_KEY=your_secret_key
HANDAAS_REQUEST_TIMEOUT=30
```

### 4. streamable-http启动服务

```bash
python server/mcp_server.py streamable-http
```

服务将在 `http://localhost:8000` 启动，MCP 地址为 `http://127.0.0.1:8000/mcp`。

#### 支持启动方式 stdio 或 sse 或 streamable-http

### 5. Cursor / Cherry Studio MCP配置

```json
{
  "mcpServers": {
    "construction-mcp-server": {
      "type": "streamableHttp",
      "url": "http://127.0.0.1:8000/mcp"
    }
  }
}
```

## STDIO版安装部署

### 设置Cursor / Cherry Studio MCP配置

```json
{
  "mcpServers": {
    "construction-mcp-server": {
      "command": "uv",
      "args": ["run", "mcp", "run", "{workdir}/server/mcp_server.py"],
      "env": {
        "PATH": "{workdir}/mcp_env/bin:$PATH",
        "PYTHONPATH": "{workdir}/mcp_env",
        "INTEGRATOR_ID": "your_integrator_id",
        "SECRET_ID": "your_secret_id",
        "SECRET_KEY": "your_secret_key"
      }
    }
  }
}
```

## 使用官方Remote服务

### 1. 直接设置Cursor / Cherry Studio MCP配置

```json
{
  "mcpServers": {
    "construction-mcp-server":{
      "type": "streamableHttp",
      "url": "https://mcp.handaas.com/construction/construction_bigdata?token={token}"
      }
  }
}
```

### 注意：integrator_id、secret_id、secret_key及token需要登录 https://www.handaas.com/ 进行注册开通平台获取


## 推荐调用流程

1. 用户只提供企业简称、品牌或关键词时，先调用 `construction_enterprise_search` 获取企业全称、`nameId` 或统一社会信用代码。
2. 调用 `construction_enterprise_project_list` 查询该企业涉及的建筑工程项目，取得项目 `_id` 和完整项目名称。
3. 使用项目 `_id` 作为 `sikuId` 查询项目综合详情、合同、施工图审查、施工许可和竣工信息。
4. 使用完整项目名称调用 `construction_project_bidding_list` 查询相关招投标信息。

如果用户不是从企业维度出发，而是直接提供项目名称、地区、用途或工程规模，可跳过前两步，直接调用 `construction_project_search`。


## 可用工具

### 1. construction_enterprise_search
**功能**: 关键词查询企业

**Product ID**: `675cea1f0e009a9ea37edaa1`

按企业简称、企业名称、品牌、产品或其他关键词查询候选企业，为企业建筑工程项目查询提供稳定主体标识。

**参数**:
- `matchKeyword` (必需): 企业简称、名称、品牌、产品或其他关键词
- `pageIndex` (可选): 页码，从1开始，默认1
- `pageSize` (可选): 每页条数，默认10，最大10

**返回值**:
- `total`: 候选企业总数
- `resultList`: 候选企业列表
  - `name`: 企业全称
  - `nameId`: 企业ID
  - `catchReason`: 关键词命中原因
  - `enterpriseType`: 企业类型
  - `operStatus`: 经营状态
  - `legalRepresentative`: 法定代表人
  - `foundTime`: 成立时间
  - `regCapitalValue`: 注册资本
  - `address`: 企业地址

### 2. construction_enterprise_project_list
**功能**: 建筑工程项目明细查询

**Product ID**: `66aba795520b164ce252e5e7`

根据企业名称、企业ID、注册号或统一社会信用代码，查询该企业涉及的全部建筑工程项目。

**参数**:
- `matchKeyword` (必需): 企业名称、企业ID、注册号或统一社会信用代码
- `keywordType` (可选): 主体类型，可选 `name`、`nameId`、`regNumber`、`socialCreditCode`，默认 `name`
- `pageIndex` (可选): 页码，从1开始，默认1
- `pageSize` (可选): 每页条数，默认10，最大10

**返回值**:
- `total`: 企业涉及的建筑工程项目总数
- `resultList`: 建筑工程项目列表
  - `_id`: 建筑项目ID，可作为后续Tool的 `sikuId`
  - `projectName`: 项目名称
  - `projectType`: 项目类型
  - `region`: 项目地区
  - `totalInvestment`: 总投资，单位元

### 3. construction_project_search
**功能**: 建筑报建项目搜索

**参数**:
- `projectNameInclude` (可选): 项目名称包含词
- `projectNameExclude` (可选): 项目名称排除词
- `biddingWinner` (可选): 中标单位
- `totalInvestment` (可选): 总投资筛选
- `region` (可选): 项目地区
- `hasCompletionAcceptance` (可选): 是否存在竣工验收
- `use` (可选): 项目用途
- `constructionNature` (可选): 建设性质
- `dataGrade` (可选): 数据等级
- `projectType` (可选): 项目类型
- `minTotalArea` / `maxTotalArea` (可选): 总面积区间
- `minTotalLength` / `maxTotalLength` (可选): 总长度区间
- `pageIndex` (可选): 页码
- `pageSize` (可选): 每页条数，默认10，最大10

**返回值**:
- `total`: 项目总数
- `resultList`: 建筑项目列表
  - `_id`: 四库项目ID，在后续Tool中作为 `sikuId`
  - `projectName`: 项目名称
  - 项目地区、用途、建设性质和工程规模等摘要字段
  - 建设单位、中标单位和项目状态等关联信息

### 4. construction_project_detail
**功能**: 建筑项目综合详情查询

**参数**:
- `sikuId` (必需): 必须使用项目搜索返回的 `_id`

**返回值**:
- `total`: 命中数量
- `resultList`: 项目综合详情
  - 项目基本信息
  - 建设单位信息
  - 勘察、设计、施工和监理等参建主体
  - 工程规模、投资、用途和建设性质

### 5. construction_project_bidding_list
**功能**: 建筑项目招投标信息查询

**参数**:
- `projectName` (必需): 建议使用项目搜索返回的完整项目名称
- `pageIndex` (可选): 页码
- `pageSize` (可选): 每页条数，默认10，最大10

**返回值**:
- `total`: 招投标记录总数
- `resultList`: 招标、采购和中标记录
  - 公告标题和公告类型
  - 招标单位、采购主体和中标单位
  - 公告时间、地区和来源链接等信息

### 6. construction_project_contract_list
**功能**: 建筑项目合同信息查询

**参数**:
- `sikuId` (必需): 项目搜索返回的项目ID
- `pageIndex` (可选): 页码
- `pageSize` (可选): 每页条数，默认10，最大10

**返回值**:
- `total`: 合同总数
- `resultList`: 项目关联合同列表
  - 合同名称和合同金额
  - 发包单位和承包单位
  - 合同类型、签订时间和状态等信息

### 7. construction_project_drawing_review_list
**功能**: 建筑项目施工图审查查询

**参数**:
- `sikuId` (必需): 项目搜索返回的项目ID
- `pageIndex` (可选): 页码
- `pageSize` (可选): 每页条数，默认10，最大10

**返回值**:
- `total`: 施工图审查记录数量
- `resultList`: 审查合格书记录
  - `projectName`: 项目名称
  - `engineeringName`: 工程名称
  - `censorNum`: 施工图审查合格书编号
  - `constructionPermitNum`: 施工许可证号
  - `releaseCertTime`: 发证时间

### 8. construction_project_permit_list
**功能**: 建筑项目施工许可查询

**参数**:
- `sikuId` (必需): 项目搜索返回的项目ID
- `pageIndex` (可选): 页码
- `pageSize` (可选): 每页条数，默认10，最大10

**返回值**:
- `total`: 施工许可记录总数
- `resultList`: 施工许可明细
  - 工程名称和施工许可证号
  - 发证机关和发证时间
  - 建设、施工、设计和监理单位
  - 关联单位人员和工程规模

### 9. construction_project_completion_list
**功能**: 建筑项目竣工信息查询

**参数**:
- `sikuId` (必需): 项目搜索返回的项目ID
- `pageIndex` (可选): 页码
- `pageSize` (可选): 每页条数，默认10，最大10

**返回值**:
- `total`: 竣工记录总数
- `resultList`: 合并后的竣工备案和验收记录
  - `recordType=completion_record`: 竣工备案
  - `recordType=completion_acceptance`: 竣工验收
  - 竣工时间、备案编号、验收信息和关联单位等字段

## 使用注意事项

1. **企业简称处理**: 企业简称不能直接用于工程项目查询时，先调用 `construction_enterprise_search` 确认企业全称或稳定ID。
2. **主体类型**: 企业工程项目查询的 `keywordType` 必须与 `matchKeyword` 内容一致。
3. **项目ID要求**: 项目详情、合同、施工图审查、施工许可和竣工查询必须使用项目列表或项目搜索返回的 `_id` 作为 `sikuId`。
4. **招投标条件**: 招投标查询使用项目完整名称进行全文匹配。
5. **施工图审查来源**: 该Tool从施工许可数据中投影已有审查合格书字段，不是独立上游接口。
6. **API限制**: 分页查询一页最多获取10条数据。
7. **合法空结果**: 未命中时返回 `total=0` 和 `resultList=[]`，不作为系统错误。
8. **监控边界**: “监控”由调用方按需重复查询实现，本服务不提供后台订阅或主动推送。

## 使用提问示例

### construction_enterprise_search (关键词查询企业)
1. “中建”对应哪些企业？
2. 通过“中国建筑”查找准确企业名称和企业ID
3. 搜索与某建筑品牌相关的候选企业

### construction_enterprise_project_list (建筑工程项目明细查询)
1. 查询中国建筑股份有限公司涉及的建筑工程项目
2. 使用企业ID查看该企业全部工程项目明细
3. 根据统一社会信用代码查询企业的项目名称、地区和总投资

### construction_project_search (建筑报建项目搜索)
1. 搜索广东名称中包含“产业园”的建筑项目
2. 查询中标单位为某公司的建筑项目
3. 查找已完成竣工验收的住宅项目

### construction_project_detail (建筑项目综合详情查询)
1. 查看刚才项目的基本信息和建设单位
2. 查询该项目有哪些参建主体
3. 获取项目投资、用途和工程规模

### construction_project_bidding_list (建筑项目招投标信息查询)
1. 查询这个产业园项目的招标公告
2. 查看该项目的中标单位和中标信息
3. 查询项目相关采购公告

### construction_project_contract_list (建筑项目合同信息查询)
1. 查看该项目的合同列表
2. 查询项目合同金额和承包单位
3. 获取该项目的发包单位信息

### construction_project_drawing_review_list (建筑项目施工图审查查询)
1. 查询该项目的施工图审查合格书编号
2. 查看审查记录关联的工程名称
3. 核对施工图审查记录和许可证号

### construction_project_permit_list (建筑项目施工许可查询)
1. 查询该项目的施工许可证
2. 查看施工许可关联的单位和人员
3. 获取施工许可发证机关和发证时间

### construction_project_completion_list (建筑项目竣工信息查询)
1. 查询该项目的竣工备案记录
2. 查看项目是否已完成竣工验收
3. 分别列出竣工备案和验收信息

## 测试验证

```bash
python -m py_compile server/mcp_server.py
python -m unittest discover -s tests -v
```

当前服务包含 10 个离线单元测试。真实接口验证需在本地 `.env` 配置有效凭据后执行，测试输出不得提交真实业务响应或凭据。