Supplier Network MCP

网络MCP服务器

用于Payvaro Network API的功能强大的MCP（模型上下文协议）服务器。提供智能供应商搜索，包括模糊匹配、供应商/买方管理、关系跟踪、网络分析和Slack通知。

主要特点

智能供应商搜索

• 模糊匹配 -即使有拼写错误、缩写或微小变化，也能找到供应商
• 多字段搜索 -按姓名、地址、电子邮件或组合匹配
• 信心评分 -获取比赛置信水平（精确、高、中、低）
• 智能排名 -按相关性排序的结果

综合管理

• 列出并搜索所有供应商和买家
• 获取完整历史记录的详细信息
• 创建买家和买家供应商链接
• 跟踪买家与供应商的关系
• 按日期范围查询审计跟踪

网络分析

• 分析 -识别隔离节点、网络集线器和连接模式
• 进口分析 -上传后验证、导入前预览、数据质量评分
• 关系分析 -健康评估、覆盖差距、网络结构图

集成

• Slack -通过webhook发布分析结果或自定义消息
• 文件上传 -上传CSV文件进行批量处理

灵活的输出

• 标记语言 -美观、易读的格式
• JSON -用于编程的结构化数据

安装

npm install
npm run build

配置

设置这些环境变量：

# Required: Your API key for authentication
export NETWORK_API_KEY="your-api-key-here"

# Optional: API base URL (defaults to http://localhost:8080)
export NETWORK_API_BASE_URL="http://localhost:8080"

# Optional: Default client ID — sent as x-client-id on every request when no per-request override is supplied
export NETWORK_CLIENT_ID="client-uuid"

# Optional: Enable admin mode — allows tools to accept a per-request `asClientId` field.
# Only enable this when the configured NETWORK_API_KEY is an admin token; the backend
# must accept header overrides from that token for this to take effect.
export NETWORK_ADMIN_MODE="true"

# Optional: Slack webhook URL for notification tools
export SLACK_WEBHOOK_URL="https://hooks.slack.com/services/..."

管理模式按请求客户端覆盖

当服务器启动时 NETWORK_ADMIN_MODE=true，每个整合工具(search, suppliers, buyers, relationships, imports, matching, analyze)接受可选 asClientId 现场。如果提供，MCP服务器将替换默认服务器 x-client-id 头球 对于单个请求，让管理员调用者在不重新配置的情况下对任何客户端的数据进行操作 服务器。

• 没有 NETWORK_ADMIN_MODE=true，通过 asClientId 被拒绝，并出现可操作的错误

在向上游发送任何请求之前。

• 搭配 lookup_client 将人类可读的客户端名称解析为其UUID的工具，然后

将该UUID传递为 asClientId 在后续的工具调用中。

• 这 lookup_client 工具本身不受影响（它读取S3，而不是Network API）。

LocalStack测试密钥

使用LocalStack进行测试：

• 完全访问: fd9896cd-5bc2-448e-a6e6-59457dc9db79
• 只读: 0379fdd7-e55d-41c0-b457-22fd3f5043a4
• 只写: 1fffd2e5-4c6c-4e69-919d-4f00ef2c786b

用法

运行服务器

stdio模式（默认）:

npm start

HTTP模式:

npm run start:http
# Server runs on http://localhost:3000/mcp

可用工具

9个整合工具提供所有供应商、买方、关系、分析、导入和通知功能。每个工具都接受一个可选 response_format 参数("markdown" 或 "json"，默认为 "markdown").

______________________________________________________________________

search --基于模糊匹配的供应商搜索

通过模糊匹配智能搜索供应商。查找重复项、匹配外部数据和处理不完美数据的主要工具。

比赛得分阈值：

• 1.0 -完全匹配
• 0.8-0.99 -高度自信
• 0.6-0.79 -中等信心
• 0.4-0.59 -低置信度（可能包括误报）

{
  "name": "Acme",
  "address": { "city": "San Francisco", "stateProvince": "CA" },
  "minMatchScore": 0.7,
  "maxResults": 5
}

______________________________________________________________________

suppliers --供应商管理

通过多种操作查看供应商信息。

行动：

• list -列出所有供应商
• get -获取详细的供应商信息
• history -获取更改后的版本历史记录
• by_date -在特定日期更新供应商

按动作列出的参数：

列表 （无必需参数）：

得到:

历史:

截止日期:

______________________________________________________________________

buyers --买方管理

查看并创建买家。

行动：

• list -列出所有买家
• get -获取详细的买家信息
• create -创建新买家

按动作列出的参数：

列表 （无必需参数）： _（无参数。）_

得到:

创造:

______________________________________________________________________

relationships --买方供应商链接

管理和查询买方-供应商关系。

行动：

• for_buyer -将供应商链接到买家
• for_supplier -将买家链接到供应商
• link -在买方和供应商之间建立联系

按动作列出的参数：

for_buyer:

for_供应商:

链接:

______________________________________________________________________

imports --文件上传和导入管理

上传和管理CSV导入。

行动：

• upload -上传CSV文件进行处理
• batches -列出导入批次
• validate -验证导入数据

按动作列出的参数：

上传:

批次:

验证:

______________________________________________________________________

matching --匹配作业管理

跟踪和管理数据匹配作业。

行动：

• jobs -列出所有匹配的职位
• job_detail -获取特定工作的详细信息
• candidates -从匹配的工作中获取候选人
• staged -查看已准备好导入的分阶段比赛

按动作列出的参数：

工作:

job_detail:

候选人:

分阶段的:

______________________________________________________________________

analyze --网络分析

全面的网络和关系分析。

行动：

• connections -分析买方-供应商网络拓扑
• relationships -分析关系健康、覆盖范围或结构
• import_quality -上传后验证和数据质量评估

按动作列出的参数：

连接:

关系:

进口_质量:

______________________________________________________________________

notify_slack --Slack通知

通过webhook向Slack发布消息。

类型：

• analysis -后网络分析结果
• custom -发送自定义格式的消息

按类型列出的参数：

分析:

定制:

消息对象：

______________________________________________________________________

lookup_client --客户端ID解析

将客户端名称解析为UUID以进行买家识别。

从配置存储中返回匹配的客户端名称和UUID。

______________________________________________________________________

常见用例

查找重复供应商

使用 search 工具：

{
  "name": "Acme Corp",
  "minMatchScore": 0.7,
  "maxResults": 5
}

这将找到“Acme Corporation”、“Acme Corp”、“Acme Co.”等。

匹配外部数据

从其他系统导入数据时：

{
  "name": "XYZ Company",
  "address": {
    "streetAddress": "123 Main St",
    "city": "Los Angeles",
    "postalCode": "90001"
  },
  "minMatchScore": 0.6
}

审计跟踪

使用查看在特定日期发生了什么变化 suppliers 带工具 by_date 动作：

{ "date": "20251210" }

然后使用以下命令获取详细的历史记录 suppliers 带工具 history 动作：

{ "id": "supplier-id-from-above", "format": "timeline" }

网络运行状况检查

运行完整的连接分析并将结果发布到Slack：

1. 呼叫 analyze 带工具 connections 动作： { "includeSuggestions": true }
2. 将结果传递给 notify_slack 带工具 analysis 类型和 { "includeDetails": true }

导入后验证

上传CSV文件后，使用验证导入的内容 imports 带工具 validate 动作：

{
  "mode": "post-upload",
  "dateRange": { "from": "20260301", "to": "20260301" },
  "buyerId": "buyer-123"
}

客户端ID查找

当您知道客户端名称但需要其UUID时，请使用 lookup_client 工具：

{ "name": "Comet Electric", "environment": "dev" }

响应格式

Markdown（人类可读）

# 🔍 Supplier Search Results

## Search Query
**Name:** Acme
**Address:** San Francisco, CA

**Total Matches Found:** 3

---

## 1. Acme Corporation ✅

**Match Score:** 87.3% (HIGH)

**Why this matches:**
- Name matches "Acme Corporation" (92%)
- Address: City: San Francisco
- Address: State: CA

**Field Matches:** Name: 92% | Address: 85%

---

**ID:** SUP#123
**Email:** contact@acme.com
**Address:** 123 Main St, San Francisco, CA 94105

JSON（结构化数据）

{
  "query": {
    "name": "Acme",
    "address": {
      "city": "San Francisco",
      "stateProvince": "CA"
    }
  },
  "totalMatches": 3,
  "matches": [
    {
      "supplier": {
        "id": "SUP#123",
        "name": "Acme Corporation",
        "email": "contact@acme.com",
        "address": { ... }
      },
      "matchScore": {
        "score": 0.873,
        "level": "high",
        "reasons": [
          "Name matches \"Acme Corporation\" (92%)",
          "Address: City: San Francisco"
        ]
      },
      "matchedFields": {
        "name": 0.92,
        "address": 0.85
      }
    }
  ]
}

技术细节

模糊匹配算法

搜索使用 模糊排序 具有加权字段匹配的库：

• 名字：权重3（最重要）

- 还检查别名 - 处理缩写和拼写错误

• 地址：权重4（对重复数据删除至关重要）

- 街道地址：Weight 3 - 城市：体重2 - 状态：重量1（要求完全匹配） - 邮政编码：重量2（支持部分ZIP匹配）

• 电子邮件：重量2

- 首选完全匹配 - 域匹配作为回退

依赖项

• @modelcontextprotocol/sdk -MCP服务器框架
• axios -API调用的HTTP客户端
• express -HTTP服务器（用于HTTP模式）
• zod -输入验证
• fuzzysort -快速模糊字符串匹配
• typescript -类型安全

打包技能

此repo提供以下参考技能 skills/ 对常见的网络mcp工作流进行编码。它们位于此处（不在共享技能目录中），因此它们与工具界面一起进行版本更新。

安装

Claude Code和Codex从各自的技能目录中自动发现技能。要使这些技能可用，请将每个技能目录符号链接（或复制）到您的本地技能存储中：

# macOS / Linux — Claude Code
for s in network-entity-lookup network-traversal network-payability-triage network-payability-coverage; do
  ln -s "$(pwd)/skills/$s" ~/.claude/skills/$s
done

# Codex
for s in network-entity-lookup network-traversal network-payability-triage network-payability-coverage; do
  ln -s "$(pwd)/skills/$s" ~/.codex/skills/$s
done

如果您的编辑器使用不同的技能布局，请复制 skills//SKILL.md 将文件放入工具所需的位置。

验证打包技能

技能是指令文本，而不是代码，所以没有自动测试。要验证更改，请执行以下操作：

1. 在本地对种子租户启动MCP： npm start （见 用法 部分）。
2. 使用安装的技能打开MCP感知客户端（Claude Desktop等）。
3. 针对已知的好对和已知的坏对调用每个技能的触发短语。
4. 确认输出与技能中的模板匹配 SKILL.md.
5. 检查 ~/Library/Logs/Claude/mcp*.log 验证称为记录工具序列的技能。

许可证

Apache 2.0

支持

对于问题或疑问：

• 检查 MCP文件
• 联系人：Payvaro网络团队