@szjc/szjc-mcp-server

MCP Server for the Shuzijiancai API, built with @modelcontextprotocol/sdk, providing integration with the IDE's MCP system.

安装

使用npm安装

npm install @szjc/szjc-mcp-server

使用yarn安装

yarn add @szjc/szjc-mcp-server

使用pnpm安装

pnpm add @szjc/szjc-mcp-server

快速开始

# 安装包
npm install @szjc/szjc-mcp-server

# 设置环境变量
export SZJC_API_TOKEN=your_api_token_here

# 启动MCP服务
npx @szjc/szjc-mcp-server

功能特性

• 基于 @modelcontextprotocol/sdk 标准实现
• 集成数字建材开放API接口
• 支持地区信息查询（省市区三级联动）
• 统一的认证管理和错误处理
• 符合MCP协议规范的工具注册和调用

技术架构

本SDK使用 @modelcontextprotocol/sdk 构建，完全符合MCP协议规范：

• 使用 MCPServer 和 MCPServerOptions 类管理服务生命周期
• 支持标准的工具注册机制
• 提供统一的错误处理和日志记录
• 支持优雅关闭和信号处理

配置

通过环境变量进行配置： 注意：SZJC_API_TOKEN、SZJC_API_AUTH_KEY、SZJC_API_AUTH_SECRET、SZJC_OIDC_CLIENT_ID、SZJC_OIDC_CLIENT_SECRET 是必填项。需提前到数字建材开放平台申请。联系邮箱：[email protected]

| 环境变量 | 描述 | 默认值 | |---------|------|-------| | SZJC_API_BASE_URL | API基础URL | https://dev-api-gateway.shuzijiancai.com | | SZJC_API_TOKEN | API访问令牌（必填） | - | | SZJC_API_AUTH_KEY | API认证密钥（必填） | - | | SZJC_API_AUTH_SECRET | API认证密钥（必填） | - | | SZJC_OIDC_CLIENT_ID | OIDC客户端ID（必填） | - | | SZJC_OIDC_CLIENT_SECRET | OIDC客户端密钥（必填） | - | | PORT | MCP服务端口 | 3000 |

使用方式

启动MCP Server

# 设置环境变量
export SZJC_API_TOKEN=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjMzMDU4MDIwMjY3MTQxMzI0OCIsImtleSI6IjRhMWYwZTk0ZmZhZTE4YzYxYjA5NDZiMTI0MGY4NDJhIiwiaWF0IjoxNzU4NzY2MjYwLCJleHAiOjE3NTkzNzEwNjAsInN1YiI6InRva2VuIn0.tqLZKjcG4tbGbVdaHYTDFk9Q2JMuPwm-L2Ke3qCLlYw

# 启动服务
npm start

可用的MCP工具

getAreasAll

功能: 获取所有地区信息，包含省市区三级联动数据

参数: 无

返回格式:

[
  {
    "id": 0,
    "name": "string",
    "children": [
      {
        "id": 0,
        "name": "string",
        "children": [
          {
            "id": 0,
            "name": "string",
            "noAdmin": 0
          }
        ]
      }
    ]
  }
]

getProvinceAll

功能: 获取所有省级区域信息

参数: 无

返回格式:

[
  {
    "id": 0,
    "name": "string"
  }
]

getMaterialClassification

功能: 获取建材的分类

参数:

• cityCode (string, 可选): 城市行政编码，必须是数字字符串

返回格式:

{
  "categories": [
    {
      "id": "string",
      "name": "string",
      "children": [
        {
          "id": "string",
          "name": "string"
        }
      ]
    }
  ]
}

getGovProjectList

功能: 获取政府项目列表

参数:

• skip (number, 可选): 跳过数量，默认为0
• take (number, 可选): 获取数量，默认为20
• provinceCode (string, 可选): 省份代码
• step (number, 可选): 步骤，默认为3
• requireOrg (number, 可选): 是否需要组织信息，默认为1
• requireMon (number, 可选): 是否需要监控信息，默认为1
• projectName (string, 可选): 项目名称
• projectCode (string, 可选): 项目编码
• status (string, 可选): 项目状态

返回格式:

{
  "data": [
    {
      "id": "string",
      "name": "string",
      "code": "string",
      "status": "string",
      "province": "string"
    }
  ],
  "total": 0,
  "skip": 0,
  "take": 20
}

getProductList

功能: 获取指定企业在绿色建材采信平台上入库建材产品

参数:

• skip (number, 可选): 跳过数量，默认为0
• take (number, 可选): 获取数量，默认为20
• orgId (string, 可选): 组织ID（与creditCode二选一必填）
• creditCode (string, 可选): 统一社会信用代码（与orgId二选一必填）
• provinceCode (string, 可选): 省份代码
• cityCode (string, 可选): 城市代码，必须是数字字符串
• includeUnclassified (number, 可选): 是否包含没有政采分类的数据，null或0=否，1=是

返回格式:

{
  "data": [
    {
      "id": "string",
      "name": "string",
      "category": "string",
      "orgId": "string",
      "orgName": "string"
    }
  ],
  "total": 0,
  "skip": 0,
  "take": 20
}

getRegionOrgList

功能: 获取指定区域的入库企业信息

参数:

• skip (number, 可选): 跳过数量，默认为0
• take (number, 可选): 获取数量，默认为20
• provinceCode (string, 必选): 省份代码
• cityCode (string, 可选): 城市代码，必须是数字字符串
• districtCode (string, 可选): 区县代码，必须是数字字符串

返回格式:

{
  "data": [
    {
      "id": "string",
      "name": "string",
      "creditCode": "string",
      "province": "string",
      "city": "string"
    }
  ],
  "total": 0,
  "skip": 0,
  "take": 20
}

health

功能: 健康检查

参数: 无

返回格式:

{
  "status": "ok",
  "timestamp": "2023-01-01T00:00:00.000Z",
  "service": "szjc-mcp-server",
  "version": "1.0.0",
  "auth": "oidc" 或 "static-token"
}

OIDC认证工具

oidcAuthUrl

功能: 获取OIDC认证URL

参数: 无

oidcCallback

功能: 处理OIDC认证回调

参数:

• code (string, 必选): 授权码
• state (string, 必选): 状态参数

oidcUserInfo

功能: 获取OIDC用户信息

参数: 无

oidcConfigHelp

功能: 获取OIDC配置帮助信息

参数: 无

setMCPConfig

功能: 设置MCP服务配置

参数:

• baseUrl (string, 可选): API基础URL
• token (string, 可选): API访问令牌
• authKey (string, 可选): API认证密钥
• authSecret (string, 可选): API认证密钥
• issuer (string, 可选): OIDC颁发者URL
• clientId (string, 可选): OIDC客户端ID
• clientSecret (string, 可选): OIDC客户端密钥
• scopes (array, 可选): OIDC权限范围

在IDE中使用

在IDE的配置文件中添加以下配置：

{
  "mcpServers": {
    "szjc": {
      "command": "npx",
      "args": [
        "-y",
        "@szjc/szjc-mcp-server"
      ],
      "env": {
        "SZJC_API_TOKEN": "YOUR_API_TOKEN",
        "PORT": "3001",
        "SZJC_API_BASE_URL": "https://dev-api-gateway.shuzijiancai.com",
        "SZJC_API_AUTH_KEY": "xxxxxx",
        "SZJC_API_AUTH_SECRET": "xxxxxx",
        "SZJC_OIDC_CLIENT_ID": "xxxxxx",
        "SZJC_OIDC_CLIENT_SECRET": "xxxxxx",
        "SZJC_OIDC_ISSUER": "https://dev-api-gateway.shuzijiancai.com",
        "SZJC_OIDC_SCOPES": "openid profile email api:authDataRead api:authGovDataRead"
      }
    }
  }
}

使用run_mcp调用

// 在Trae IDE中调用getAreasAll工具
const result = await run_mcp({
  server_name: "szjc",
  tool_name: "getAreasAll",
  args: {}
});

console.log("地区信息:", result);

开发

# 安装依赖
npm install

# 构建
npm run build

# 启动
npm start

项目结构

szjc-mcp-sdk-node/
├── src/
│   ├── api/             # API调用模块
│   │   ├── baseApi.js   # 基础API类
│   │   ├── common.js    # 通用API实现（地区、建材分类等）
│   │   └── resource.js  # 资源API实现（政府项目、产品、企业等）
│   ├── auth/            # 认证模块
│   │   ├── client.js    # 认证客户端
│   │   ├── oidcClient.js # OIDC认证客户端
│   │   └── oidcConfig.js # OIDC配置管理
│   ├── config/          # 配置管理
│   │   └── configManager.js # 配置管理器
│   ├── resource/        # 资源文件
│   │   └── all.json     # 地区数据
│   ├── utils/           # 工具函数
│   │   └── helpers.js   # 辅助函数
│   └── index.js         # MCP服务入口（使用@modelcontextprotocol/sdk）
├── package.json         # 项目配置
├── package-lock.json    # 依赖锁定文件
├── .gitignore          # Git忽略文件
├── .npmignore          # NPM忽略文件
├── PUBLISH_GUIDE.md    # 发布指南
├── publish.sh          # 发布脚本
└── README.md           # 文档

相关文档

• Model Context Protocol SDK文档
• npm发布指南