Skip to main content
Glama
xtshK

Procurement MCP Server

by xtshK
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Local

Procurement MCP Server

一個以 IT 採購流程為題的 MCP (Model Context Protocol) server 學習專案。 它把既有的採購後端 (REST API) 包裝成 AI 可呼叫的工具,讓 Claude 等 AI 能透過自然語言查詢採購資料。

架構

AI client ──(MCP / stdio)──▶ 本 server ──(HTTP + JWT)──▶ 採購後端 REST API

本 server 不做業務邏輯,只負責把後端能力轉成 MCP 工具,並處理登入與認證。

Related MCP server: caseware-ai-procurement-knowledge-platform

目前提供的工具

工具

說明

對應的後端端點

check_backend_health

檢查後端是否正常運作

GET /api/health

search_purchase_orders

依關鍵字搜尋採購單,可選狀態碼篩選與筆數限制

GET /api/purchase-orders/search

get_purchase_order_details

查單一採購單明細:品項、送達與付款資訊、發票、附件

GET /api/purchase-orders/search + GET /api/purchase-orders/:id/details

check_esign_status

查電子簽核進度與每位簽署人的狀態

GET /api/esign/requests

幾個實作上的注意事項:

  • get_purchase_order_details 會串接兩個後端呼叫。 後端明細 API 的 :id 是資料庫的數字 id,不是採購單號,所以工具先用搜尋把單號換成 id 再取明細。 單號沒有完全命中時會列出相近選項請使用者指定,不會自己猜一筆。

  • 後端的 warning 欄位會照實轉達。 後端向 FreshService 取資料失敗時, 回傳的品項會是空的並附上 warning。工具會明確說明這是「取不到」而不是 「沒有」——否則 AI 會把失敗講成「這張單沒有品項」。

  • check_esign_status 依採購單查詢是「文字比對」,不是資料關聯。 後端的 esign_requests 表只存廠商、主旨與簽署人,沒有採購單欄位, 所以只能比對簽核主旨裡有沒有出現單號或發票號。工具的輸出會標明這一點: 比對不到不代表該採購單沒有送簽。若要真正的關聯,需要在後端的 esign_requests 加上 po_number 之類的欄位。

開發環境設定

需求:Node.js 20+。

npm install
cp .env.example .env   # 然後填入 BACKEND_URL 與登入帳密
npm run dev            # 用 tsx 直接執行 index.ts

可用的 npm script:

指令

用途

npm run dev

tsx watch,改檔就重啟

npm start

tsx 直接跑一次

npm run build

用 tsc 編譯到 dist/

npm run serve

跑編譯後的 dist/index.js

npm test

跑回歸測試(見下)

測試

npm test

測試會真的把 index.ts 跑起來,用 MCP 協定呼叫每個工具,後端則換成 test/mock-backend.mjs——一個回傳格式照著真後端抄的假後端。所以測到的是 整條路:zod 參數驗證 → 登入帶 token → 呼叫後端 → 後處理 → 排版輸出。 不需要啟動真的採購後端,也不會碰到網路。

test/
├── mock-backend.mjs   假後端(回傳格式對齊真後端的 route)
├── mcp-client.mjs     用 stdio 講 MCP 的極簡測試 client
└── tools.test.mjs     各工具的回歸測試

⚠️ 真後端改了回傳欄位時,test/mock-backend.mjs 也要跟著改, 否則測試會綠但實際是壞的。

環境變數 (.env)

變數

說明

BACKEND_URL

採購後端位置,預設 http://localhost:3001

BACKEND_EMAIL

後端登入帳號

BACKEND_PASSWORD

後端登入密碼

⚠️ .env 含密碼,已被 .gitignore 忽略,請勿 commit。

連接到 Claude Desktop

在 claude_desktop_config.json 的 mcpServers(小寫)加入:

{
  "mcpServers": {
    "procurement": {
      "command": "npx",
      "args": ["tsx", "/absolute/path/to/index.ts"]
    }
  }
}

修改程式後需以 Cmd+Q 完整結束並重新開啟 Claude Desktop。

Available Tools

2 tools
check_backend_health檢查採購後端健康狀態A

檢查採購流程後端服務是否正常運作。會呼叫後端的 /api/health 端點。當使用者想確認系統是否上線,或在做其他操作前想先確認連線時使用。

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.2/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It discloses the endpoint and the checking behavior, but does not describe the return format, error handling, authentication needs, or whether any side effects occur. This is adequate for a simple health check but not rich.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise, consisting of two sentences that front-load the main purpose and the endpoint, followed by clear usage scenarios. No unnecessary information is included.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no parameters and no output schema, the tool is simple. The description covers the purpose and when to use it, but does not mention what the response or result looks like, which could be useful for a health check. Still, it is mostly complete for the tool's simplicity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, so there is no parameter information needed. The baseline of 4 applies, and the description adds no parameter-specific detail because there are none to document.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: checking whether the procurement backend service is operating normally, with the specific implementation detail of calling the /api/health endpoint. This distinguishes it from the sibling tool search_purchase_orders, which is a different operation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly states when to use the tool: when the user wants to confirm the system is online, or before performing other operations to verify connectivity. It does not mention alternatives or exclusions, but the context is clear enough.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_purchase_orders搜尋採購單A

依關鍵字搜尋採購單(會比對採購單號 po_number 或名稱 name),可選擇性地只篩選特定狀態、並限制回傳筆數。當使用者想查詢、尋找採購單時使用,例如「幫我找已核准的螢幕採購單,最多 5 筆」。

ParametersJSON Schema
NameRequiredDescriptionDefault
qYes搜尋關鍵字,可以是採購單號或採購單名稱的一部分
limitNo可選:最多回傳幾筆,預設 20
statusNo可選:只篩選特定狀態碼的採購單,例如 15(已下單)、25(已收貨)

TDQS

A4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

無 annotations 提供，描述必須承擔行為揭露責任。描述說明了關鍵字比對範圍（po_number/name）、可選狀態篩選與回傳筆數限制，但未提及回傳格式、錯誤行為或權限需求，屬於最低必要資訊，未達充分透明。

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

描述僅用兩句話即包含用途、比對欄位、可選篩選、回傳限制與使用範例，重點前置，無冗詞或重複資訊，結構精簡。

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

工具為搜尋型，無輸出 schema，描述已提供搜尋方式、篩選條件與筆數限制等核心資訊，足以讓代理安全呼叫。缺少回傳資料結構細節，但在無輸出 schema 下仍屬可接受的完整度。

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema 對 3 個參數的覆蓋率達 100%，描述未額外補充參數的格式或邊界，僅以實例說明 limit 與 status 的用法，但未提供超越 schema 的語意，因此維持基線分數。

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

描述明確指出工具用途為『依關鍵字搜尋採購單』，並具體說明比對欄位（po_number 或 name），與唯一兄弟工具 check_backend_health 有清楚區隔，功能定位無歧義。

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

描述提供明確使用情境『當使用者想查詢、尋找採購單時使用』，並附具體範例（找已核准螢幕採購單最多 5 筆），足以引導代理正確選用。雖未明確說明何時不使用，但與兄弟工具的健康檢查用途無重疊，指引已足夠。

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 2 tool updatesv1.0.0
    • First observedcheck_backend_health
    • First observedsearch_purchase_orders
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4/5.0
Disambiguation5/5

The two tools are completely distinct: one checks backend health, the other searches purchase orders. There is no overlap or ambiguity in their purposes.

Naming Consistency5/5

Both tools follow a consistent verb_noun pattern with snake_case: check_backend_health and search_purchase_orders. The naming convention is uniform and predictable.

Tool Count3/5

With only 2 tools, the server feels thin for a procurement domain. The count is borderline—reasonable for a tiny read-only utility, but not enough for a full procurement MCP server.

Completeness2/5

The surface only provides search and health check. Missing are essential operations like create, update, delete, or get-by-id for purchase orders. This is a significant gap for a procurement-focused server.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • PP/DS MCP Server

    LINZO-AT
    F
    license
    Not graded
    quality
    D
    maintenance
    Enables AI-assisted planning inquiries by exposing PP/DS OData APIs as MCP tools for SAP S/4HANA, allowing natural language queries about planned orders, production orders, and work centers.
    -

  • sap-mcp-server

    Volshin
    F
    license
    Not graded
    quality
    C
    maintenance
    Enables natural language querying of SAP business partner data by exposing OData APIs as MCP tools for LLM agents.
    -

  • ariba-mcp

    shafquat-quadar
    A
    license
    Not graded
    quality
    C
    maintenance
    A metadata-driven MCP server that exposes selected SAP Ariba OpenAPI operations as configurable tools, enabling secure interaction with Ariba APIs through natural language.
    MIT

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/xtshK/01_procurement_mcp_server'

If you have feedback or need assistance with the MCP directory API, please join our Discord server