Skip to main content
Glama
hieuluongxuan

HimiTrace MCP Server

by hieuluongxuan
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Hybrid

HimiTrace MCP Server — Blockchain Product Traceability for AI Agents (TypeScript Port)

Polygon Mainnet Model Context Protocol Node.js

HimiTrace is a Model Context Protocol (MCP) server that connects AI agents directly to the Polygon Mainnet blockchain to check product authenticity, verify origins, and inspect supply chain event lineages. Developed by HimiTek (himitek.com), it bridges immutable on-chain trust data with natural language queries for AI agents.

This allows any MCP-compatible AI agent (such as Claude Desktop, Cursor, Windsurf, or ChatGPT) to query, track, and audit physical goods on-chain in plain language.

Key Features

  • On-Chain Verification: Verify if a product or batch ID is registered on the Polygon blockchain (tamper-proof, immutable).

  • Supply Chain Timeline (GS1 EPCIS compatible): Retrieve the full chronological event log of a product (harvesting, processing, packaging, shipping) directly from Polygon.

  • Certificate Verification: Access quality certificates (USDA Organic, VietGAP, Fair Trade, etc.) stored on IPFS with their hashes anchored on-chain.

  • BOM (Bill of Materials) Lineage: Trace parent-child merge/split relationships of raw material batches.

  • Zero Gas Cost: All read operations from the smart contract are 100% free and do not require any crypto tokens (POL) to be spent by the AI agent.

Related MCP server: Blockchain Verification MCP

Technical Specifications

  • Contract Address: 0xFF7A3429427aFda56b2994B2F3eeF4464b851EE0

  • Network: Polygon Mainnet (Chain ID: 137)

  • Framework: built on Anthropic's Model Context Protocol (MCP) SDK using TypeScript and ethers.js (v6).

Installation & Setup

1. Prerequisites

  • Node.js v20 or higher

  • npm

2. Install Dependencies

Clone the repository and install the packages:

npm install

3. Build the Project

Compile TypeScript to Javascript:

npm run build

4. Test Connection

Ensure that the server can connect to the Polygon contract and query tools locally:

npm run test:local

If you see ALL TESTS PASSED, your environment is configured correctly.

Connecting to AI Clients

1. Claude Desktop

Add HimiTrace MCP to your Claude Desktop configuration file.

  • Windows: %APPDATA%\Claude\claude_desktop_config.json

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Add the following to the mcpServers object:

{
  "mcpServers": {
    "himitrace-mcp": {
      "command": "node",
      "args": [
        "C:/path/to/your/himitrace-mcp/dist/index.js"
      ]
    }
  }
}

Note: Make sure to replace C:/path/to/your/himitrace-mcp/dist/index.js with the actual absolute path to your compiled entry point.

2. Cursor or Windsurf IDE

In Cursor settings:

  1. Go to Settings > Features > MCP.

  2. Click + Add New MCP Server.

  3. Fill in the fields:

    • Name: HimiTrace

    • Type: command

    • Command: node "C:/path/to/your/himitrace-mcp/dist/index.js"

Available Tools

AI agents can execute the following tools:

1. verify_product

Checks if a product exists on-chain and retrieves its registration parameters.

  • Argument: product_id (string, e.g., LOT-20260315-A1B2C3)

  • Returns: JSON containing verification status, name, origin, owner, registration date, and explorer links.

2. get_trace_history

Retrieves the complete supply chain history (timeline) of a product.

  • Argument: product_id (string)

  • Returns: Chronological array of events, including event types, timestamps, custom payload data (GS1 EPCIS standard), and the recorder's blockchain wallet address.

3. get_certificates

Retrieves certificates attached to a product.

  • Argument: product_id (string)

  • Returns: Lists certificate types, issuers, dates of issue/expiration, and secure IPFS gateway links.

4. get_batch_lineage

Traces the Bill of Materials (BOM) lineage (splits and merges of batches).

  • Argument: batch_id (string)

  • Returns: Parent-child relationships, quantities, and units of raw material inputs.

5. check_product_exists

Quick check for product presence.

  • Argument: product_id (string)

  • Returns: True/False status.

6. get_system_stats

Provides overall system statistics.

  • Returns: Registered products count, contract details, and wallet balance.

Available Resources

AI agents can reference the following static resources:

  • himitrace://info: General system documentation, compliant industries, and standards.

  • himitrace://contract: Blockchain metadata (chain_id, RPC node, contract code version).

  • himitrace://pricing: Pricing tiers for API limits (Free, Pro, Enterprise).

License & Support

Developed and maintained by HimiTek Joint Stock Company.

Available Tools

6 tools
check_product_existsA

Quick check if a product ID is registered on the blockchain. Returns boolean status.

ParametersJSON Schema
NameRequiredDescriptionDefault
product_idYesThe product/batch ID to check

TDQS

A3.8/5.0
Behavior3/5

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

No annotations provided, so description must carry burden. States it's a check returning boolean, but does not disclose side effects, permissions, or rate limits. Adequate for a read-only check but lacks extra context.

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?

Two sentences, no wasted words, front-loaded with key action and output. Highly concise.

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?

Simple tool with one parameter and no output schema. Description covers purpose and output type fully. Minor gap: does not mention sync/async or error behavior.

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 description coverage is 100% for product_id, and description repeats 'product ID' without adding new meaning or syntax details. Baseline score of 3 is appropriate.

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?

Clearly states the verb 'check', resource 'product ID on blockchain', and output 'boolean status'. Distinguishes from siblings like get_batch_lineage and verify_product by emphasizing it's a quick existence check.

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

Usage Guidelines3/5

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

Mentions 'Quick check' implying speed and simplicity, but does not explicitly state when to use versus alternatives like verify_product. No exclusion or when-not context provided.

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

get_batch_lineageB

Get the Bill of Materials (BOM) lineage for a batch showing merge/split history of ingredients.

ParametersJSON Schema
NameRequiredDescriptionDefault
batch_idYesThe batch/lot ID to trace

TDQS

B3.4/5.0
Behavior2/5

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

No annotations provided, so description carries full burden. It implies read-only behavior by stating 'showing', but lacks details on error handling, auth needs, or what happens if batch_id is invalid.

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?

Single sentence with no wasted words. Front-loads the core purpose.

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

Completeness2/5

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

Given no output schema and no annotations, the description is too brief. It omits expected return format, error behavior, and guidance on when to use siblings, leaving gaps for effective agent invocation.

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 coverage is 100% with a clear description for batch_id. The description adds context about BOM lineage but does not significantly enhance parameter understanding beyond the 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?

The description clearly states the tool retrieves BOM lineage with merge/split history, using a specific verb and resource. It distinguishes from siblings like get_trace_history by focusing on BOM and merge/split details.

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

Usage Guidelines3/5

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

Usage is implied by the description but no explicit guidance on when to use this versus alternatives. No when-not or exclusion criteria provided.

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

get_certificatesA

Get all quality certificates (VietGAP, USDA Organic, Fair Trade) attached to a product, with IPFS download links.

ParametersJSON Schema
NameRequiredDescriptionDefault
product_idYesThe product/batch ID

TDQS

A3.5/5.0
Behavior2/5

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

With no annotations provided, the description carries the full burden for behavioral disclosure. It reveals that certificates are returned with IPFS links, but omits details like read-only nature, error handling (e.g., missing product_id), or any side effects.

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?

Single sentence, no redundant information. The verb 'Get' is front-loaded, and the sentence efficiently conveys the resource and key features (examples and IPFS links).

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

Completeness3/5

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

The tool is simple (one param, no output schema), but the description lacks details about the return format or structure. While it mentions IPFS links, an agent would benefit from knowing whether the response is a list or object, and what fields are included.

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 coverage is 100% and the schema description already defines 'product_id' as 'The product/batch ID'. The tool description adds no additional semantic context about the parameter beyond what the schema provides.

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: retrieving quality certificates (with examples) and IPFS download links for a product. It effectively distinguishes from sibling tools, which focus on existence checks, lineage, stats, history, and verification.

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

Usage Guidelines3/5

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

No explicit guidance on when to use this tool vs alternatives. The purpose is implied by the description, but there is no mention of exclusions or context-appropriate usage, leaving the agent to infer from sibling names.

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

get_system_statsA

Get overall statistics of the HimiTrace system, including total registered products, wallet balance, and contract info.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4/5.0
Behavior3/5

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

No annotations are present, so the description alone must convey behavior. It discloses that the tool returns three types of information, indicating a safe read operation. Nonetheless, it lacks details on data freshness, caching, or potential errors, which would aid agent decision-making.

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 a single, front-loaded sentence that immediately states the tool's purpose. Every word contributes value, with no superfluous content.

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

Completeness3/5

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

The tool is simple with no output schema. The description lists three returned fields with 'including', implying incompleteness. For full completeness, it should explicitly state all return values or confirm the list is exhaustive.

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

Parameters5/5

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

The input schema has zero parameters, so the description's role is to clarify what the tool returns. It adds meaning by enumerating the returned statistics beyond the empty schema, which is perfectly appropriate for a parameterless tool.

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 uses the specific verb 'Get' and identifies the resource as 'overall statistics of the HimiTrace system'. It explicitly lists included data points (total registered products, wallet balance, contract info), which clearly distinguishes it from sibling tools that focus on specific items like products or certificates.

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

Usage Guidelines3/5

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

The description implies usage for system-level overviews by listing global statistics, contrasting with siblings that target specific entities. However, no explicit guidance on when to use this tool versus alternatives or when not to use it is provided.

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

get_trace_historyA

Get the complete supply chain timeline (events like harvest, process, ship) for a product registered on the Polygon blockchain.

ParametersJSON Schema
NameRequiredDescriptionDefault
product_idYesThe product/batch ID

TDQS

A3.7/5.0
Behavior2/5

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

With no annotations provided, the description fully bears the burden of behavioral disclosure. It states 'complete supply chain timeline' but does not mention read-only nature, sorting, pagination, or any blockchain-specific behaviors like indexing delays.

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 a single, front-loaded sentence that efficiently communicates the tool's purpose with examples. No redundant words.

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

Completeness3/5

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

For a simple tool with one parameter, the description covers the basic purpose and domain. However, without an output schema, it lacks details about the return structure, ordering, or any limits, which would be valuable for an agent.

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?

Schema coverage is 100%, so baseline is 3. The description adds context by specifying 'registered on the Polygon blockchain', which adds meaning beyond the schema's parameter description. However, it does not provide additional format or usage details for the parameter.

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 verb 'Get', the resource 'complete supply chain timeline', and specifies the domain 'Polygon blockchain'. Examples of events (harvest, process, ship) differentiate it from sibling tools like get_batch_lineage.

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

Usage Guidelines3/5

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

The description does not explicitly state when to use this tool versus alternatives, but the examples imply it's for a timeline of events. No exclusions or when-not guidance is provided.

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

verify_productA

Verify if a product exists on the HimiTrace blockchain and retrieve its basic information including name, origin, owner, and registration date.

ParametersJSON Schema
NameRequiredDescriptionDefault
product_idYesThe product/batch ID (e.g., LOT-20260315-A1B2C3)

TDQS

A4.3/5.0
Behavior3/5

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

No annotations are provided, so the description must independently disclose behavior. It reveals that the tool is read-only (verify) and returns specific fields, but it does not mention error handling for nonexistent products, authentication requirements, or side effects.

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 a single sentence that is front-loaded with the tool's purpose. Every word is meaningful, and there is no redundancy or fluff.

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

Completeness5/5

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

Despite the absence of an output schema and annotations, the description sufficiently sets expectations by listing the returned fields (name, origin, owner, registration date). For a simple tool with one parameter, this is complete.

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?

Schema coverage is 100% with one parameter. The description adds value beyond the schema by providing an example format (e.g., 'LOT-20260315-A1B2C3') and clarifying that the parameter is a product/batch ID.

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 uses the specific verb 'verify' and resource 'product' on the HimiTrace blockchain. It clearly states what the tool does (existence check + info retrieval) and distinguishes from the sibling 'check_product_exists' which likely only checks existence.

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 implies usage for verifying existence and retrieving basic info. While it doesn't explicitly state when not to use or name alternatives, the context of sibling tools provides enough differentiation for an AI agent.

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.

  1. 6 tool updatesv1.0.0
    • First observedcheck_product_exists
    • First observedget_batch_lineage
    • First observedget_certificates
    • First observedget_system_stats
    • First observedget_trace_history
    • First observedverify_product
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.9/5.0

Scored across 6 tools

Disambiguation5/5

Each tool targets a distinct aspect: existence check, basic info, batch lineage, certificates, system stats, and supply chain timeline. No two tools have overlapping purposes.

Naming Consistency4/5

All tools follow verb_noun pattern in snake_case, but there's a minor inconsistency with 'check_product_exists' vs 'verify_product' both dealing with existence using different verbs.

Tool Count5/5

6 tools is well-scoped for a blockchain traceability domain, covering essential queries without being excessive or insufficient.

Completeness4/5

Covers main read operations: existence, details, batch lineage, certificates, history, and system stats. Missing write operations like registration or update, but for a query-focused server it's reasonably complete.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers