linkd-mcp-server

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

[!IMPORTANT] Non-Custodial Regulatory Disclaimer: This software is provided as a set of non-custodial protocol tools and interfaces. It does not provide financial services, investment advice, or asset management. All transaction signing and private key management are handled locally by the user. This implementation is designed to align with the Kenyan VASP Act 2025 standards for non-custodial decentralized protocols.

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.

Source Structure

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

Tools Exposed

Tool	Auth Required	Returns	Description
init_escrow	Admin keypair (external)	XDR string	Initialize Soroban escrow contract with roles and token
add_milestone	Admin keypair (external)	XDR string	Append a funding milestone
deposit_funds	Donor keypair (external)	XDR string	Lock SEP-41 tokens into escrow
submit_proof	NGO keypair (external)	XDR string	Attach KRA eTIMS / IPFS proof hash to milestone
approve_ngo	NGO keypair (external)	XDR string	NGO cryptographic sign-off on milestone
approve_auditor	Auditor keypair (external)	XDR string	Auditor cryptographic sign-off — triggers fund release if NGO also approved
refund_milestone	Admin keypair (external)	XDR string	Cancel stalled milestone, route capital to refund address
get_escrow_status	None	Text report	Live on-chain read: total escrowed, milestone count, full state
audit_expenditure_anchor	None	JSON audit report	Recompute bundle hash and verify against Stellar Memo.hash

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.