linkd-mcp-server

Node.js / TypeScript — Model Context Protocol server exposing Linkdfund protocol tools to AI agents.

What This Is

Bridges the Linkdfund smart contract layer to any MCP-compatible AI client (Claude Desktop, Claude Code, custom agents). It:

1. Exposes Soroban contract operations as callable tools — each returns a base64 XDR envelope, never a signed transaction.

2. Provides audit_expenditure_anchor for cross-layer cryptographic verification of expenditure bundles.

3. Runs on stdio transport — no HTTP port, no persistent process, no authentication surface.

It wraps linkd-ts-sdk. It does not contain business logic of its own.

Related MCP server: Amanah MCP

Source Structure

src/
  index.ts    Single file — MCP server, tool registry, all handlers

Tools Exposed

All XDR-returning tools produce envelopes that must be signed externally before submission.

audit_expenditure_anchor — Cross-Layer Integrity Check

This tool is the tamper-evidence proof. Given an expenditure bundle and its claimed Stellar transaction hash, it:

1. Recomputes generateExpenditureHash(invoiceNumber, amount, supplierName, donorIds) — deterministic

2. Fetches the Stellar transaction from Horizon by stellarTxHash

3. Decodes MEMO_HASH (base64 → hex)

4. Compares computed hash to on-chain hash

{
  "audit_passed": true,
  "expected_hash": "a3f9...",
  "on_chain_hash": "a3f9...",
  "variance_detected": false
}

variance_detected: true means the expenditure bundle was tampered or the wrong TX hash was supplied.

Known Limitation: The current implementation in src/index.ts passes raw donor IDs directly to generateExpenditureHash() instead of routing through generateAnonymizedExpenditureHash(). This produces a hash that diverges from the one anchored by linkd-app (which anonymizes donor IDs before hashing). The audit_passed result will be false for any real anchored expenditure until this is corrected to use generateAnonymizedExpenditureHash().

Setup & Deployment

Prerequisites

linkd-ts-sdk must be built before this package:

cd ../linkd-ts-sdk && npm run build

Install & Build

npm install
npm run build    # Compiles to dist/ — required before connecting to Claude Desktop

Development

npm run dev    # ts-node watch mode

Claude Desktop Integration

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "linkd-protocol": {
      "command": "node",
      "args": ["/absolute/path/to/linkd-mcp-server/dist/index.js"]
    }
  }
}

Transport

StdioServerTransport — communicates via stdin/stdout. No network listener. No port. No authentication surface.

Zod Validation

All tool inputs are validated with Zod before reaching linkd-ts-sdk. Validation errors are returned as structured text so agents can self-correct:

Argument Validation Failed: [ZodError details]
Runtime Error: [message]

Do not catch and swallow these — they are the agent's feedback loop.

Network

Hardcoded to testnet in src/index.ts. The audit_expenditure_anchor tool hits https://horizon-testnet.stellar.org.

Before mainnet deployment: change network: "testnet" → network: "mainnet" and update the Horizon URL. That is the only required change.

Dependency Chain

linkd-mcp-server
  └── linkd-ts-sdk (local — file:../linkd-ts-sdk — must be built first)
  └── @modelcontextprotocol/sdk
  └── @stellar/stellar-sdk ^14.5.0
  └── zod

Version divergence: linkd-mcp-server depends on @stellar/stellar-sdk ^14.5.0 while linkd-ts-sdk uses ^13.3.0. This is a latent incompatibility. Stellar SDK has breaking changes between minor versions. Both packages must be aligned before mainnet deployment.

If linkd-ts-sdk changes, run npm run build in linkd-ts-sdk/ first, then rebuild this package.

Security

This service assumes a trusted relationship with the invoking AI agent or client application. It guarantees structural validity of XDR payloads via the SDK and prevents execution halts via Zod schemas. The business logic of when to invoke these tools must be governed by the parent application's intelligence layer.

License

Proprietary. All rights reserved.