@sardis/mcp-server 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,69 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2025-01-27
+
+### Added
+
+- Initial release of the Sardis MCP Server
+- 36 MCP tools for AI agent payment operations
+- **Wallet Tools (5)**:
+  - `sardis_get_wallet` - Get wallet details and configuration
+  - `sardis_get_balance` - Get current wallet balance and spending limits
+  - `sardis_create_wallet` - Create a new MPC wallet with optional spending policy
+  - `sardis_update_wallet_policy` - Update the spending policy for a wallet
+  - `sardis_list_wallets` - List all wallets
+- **Payment Tools (3)**:
+  - `sardis_pay` - Execute a secure payment with policy validation
+  - `sardis_get_transaction` - Get transaction status and details
+  - `sardis_list_transactions` - List recent transactions
+- **Policy Tools (3)**:
+  - `sardis_check_policy` - Check if a payment would be allowed
+  - `sardis_validate_limits` - Validate spending against limits
+  - `sardis_check_compliance` - Check vendor against compliance rules
+- **Hold Tools (6)**:
+  - `sardis_create_hold` - Create a pre-authorization hold
+  - `sardis_capture_hold` - Capture a previously created hold
+  - `sardis_void_hold` - Void/cancel a hold
+  - `sardis_get_hold` - Get hold status and details
+  - `sardis_list_holds` - List active holds
+  - `sardis_extend_hold` - Extend the expiration of a hold
+- **Agent Tools (4)**:
+  - `sardis_create_agent` - Create a new AI agent
+  - `sardis_get_agent` - Get agent details
+  - `sardis_list_agents` - List all agents
+  - `sardis_update_agent` - Update agent configuration
+- **Card Tools (6)**:
+  - `sardis_issue_card` - Issue a virtual card
+  - `sardis_get_card` - Get virtual card details
+  - `sardis_list_cards` - List all virtual cards
+  - `sardis_freeze_card` - Temporarily freeze a card
+  - `sardis_unfreeze_card` - Unfreeze a card
+  - `sardis_cancel_card` - Permanently cancel a card
+- **Fiat Tools (4)**:
+  - `sardis_fund_wallet` - Fund from bank account
+  - `sardis_withdraw_to_bank` - Withdraw to bank account
+  - `sardis_get_funding_status` - Check funding status
+  - `sardis_get_withdrawal_status` - Check withdrawal status
+- **Approval Tools (2)**:
+  - `sardis_request_approval` - Request human approval
+  - `sardis_get_approval_status` - Check approval status
+- **Spending Analytics Tools (3)**:
+  - `sardis_get_spending_summary` - Get spending summary
+  - `sardis_get_spending_by_vendor` - Get spending by vendor
+  - `sardis_get_spending_by_category` - Get spending by category
+
+### Features
+
+- Financial Hallucination Prevention through policy validation
+- Simulated mode for testing without API key
+- Claude Desktop and Cursor integration support
+- Natural language spending policies
+- Risk scoring for each payment request
+- Human-in-the-loop approval workflows
+
+[0.1.0]: https://github.com/sardis-network/sardis/releases/tag/mcp-server-v0.1.0

package/CLAUDE_DESKTOP_CONFIG.md

@@ -0,0 +1,180 @@
+# Claude Desktop Configuration for Sardis
+
+Copy-paste configurations for Claude Desktop.
+
+## Configuration File Location
+
+| OS | Path |
+|----|------|
+| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |
+| Windows | `%APPDATA%\Claude\claude_desktop_config.json` |
+| Linux | `~/.config/Claude/claude_desktop_config.json` |
+
+## Quick Start (Simulated Mode)
+
+Use this configuration to get started immediately without an API key:
+
+```json
+{
+  "mcpServers": {
+    "sardis": {
+      "command": "npx",
+      "args": ["@sardis/mcp-server", "start"]
+    }
+  }
+}
+```
+
+## Production Configuration
+
+For live transactions with your Sardis account:
+
+```json
+{
+  "mcpServers": {
+    "sardis": {
+      "command": "npx",
+      "args": ["@sardis/mcp-server", "start"],
+      "env": {
+        "SARDIS_API_KEY": "sk_live_YOUR_API_KEY_HERE",
+        "SARDIS_WALLET_ID": "wal_YOUR_WALLET_ID",
+        "SARDIS_MODE": "live"
+      }
+    }
+  }
+}
+```
+
+## Full Configuration (All Options)
+
+```json
+{
+  "mcpServers": {
+    "sardis": {
+      "command": "npx",
+      "args": ["@sardis/mcp-server", "start"],
+      "env": {
+        "SARDIS_API_KEY": "sk_live_YOUR_API_KEY_HERE",
+        "SARDIS_WALLET_ID": "wal_YOUR_WALLET_ID",
+        "SARDIS_AGENT_ID": "agt_YOUR_AGENT_ID",
+        "SARDIS_MODE": "live"
+      }
+    }
+  }
+}
+```
+
+## Using with Global Install
+
+If you installed globally with `npm install -g @sardis/mcp-server`:
+
+```json
+{
+  "mcpServers": {
+    "sardis": {
+      "command": "sardis-mcp",
+      "args": ["start"]
+    }
+  }
+}
+```
+
+## Using with Local Project
+
+If the package is installed in your project's node_modules:
+
+```json
+{
+  "mcpServers": {
+    "sardis": {
+      "command": "node",
+      "args": ["./node_modules/@sardis/mcp-server/dist/cli.js", "start"]
+    }
+  }
+}
+```
+
+## Adding to Existing Configuration
+
+If you already have other MCP servers configured:
+
+```json
+{
+  "mcpServers": {
+    "your-existing-server": {
+      "command": "...",
+      "args": ["..."]
+    },
+    "sardis": {
+      "command": "npx",
+      "args": ["@sardis/mcp-server", "start"]
+    }
+  }
+}
+```
+
+## Environment Variables Reference
+
+| Variable | Description | Example |
+|----------|-------------|---------|
+| `SARDIS_API_KEY` | Your API key from sardis.network | `sk_live_abc123...` |
+| `SARDIS_WALLET_ID` | Default wallet for operations | `wal_xyz789...` |
+| `SARDIS_AGENT_ID` | Agent ID for this connection | `agt_def456...` |
+| `SARDIS_MODE` | `live` or `simulated` | `simulated` |
+
+## Verifying Installation
+
+After configuration, restart Claude Desktop. You should see Sardis tools available:
+
+1. Open Claude Desktop
+2. Start a new conversation
+3. Ask: "What Sardis tools do you have access to?"
+4. Claude should list the 36 Sardis payment tools
+
+## Troubleshooting
+
+### Tools not appearing
+
+1. Verify the JSON syntax is valid
+2. Restart Claude Desktop completely
+3. Check the config file path for your OS
+
+### "Command not found" error
+
+1. Ensure Node.js 18+ is installed: `node --version`
+2. Try using the full path to npx: `/usr/local/bin/npx` (macOS/Linux)
+3. Or install globally: `npm install -g @sardis/mcp-server`
+
+### API errors in live mode
+
+1. Verify your API key is correct
+2. Check your wallet ID exists
+3. Ensure sufficient balance for operations
+
+## Available Tools (36)
+
+After configuration, Claude will have access to:
+
+**Wallet**: sardis_get_wallet, sardis_get_balance, sardis_create_wallet, sardis_update_wallet_policy, sardis_list_wallets
+
+**Payment**: sardis_pay, sardis_get_transaction, sardis_list_transactions
+
+**Policy**: sardis_check_policy, sardis_validate_limits, sardis_check_compliance
+
+**Hold**: sardis_create_hold, sardis_capture_hold, sardis_void_hold, sardis_get_hold, sardis_list_holds, sardis_extend_hold
+
+**Agent**: sardis_create_agent, sardis_get_agent, sardis_list_agents, sardis_update_agent
+
+**Card**: sardis_issue_card, sardis_get_card, sardis_list_cards, sardis_freeze_card, sardis_unfreeze_card, sardis_cancel_card
+
+**Fiat**: sardis_fund_wallet, sardis_withdraw_to_bank, sardis_get_funding_status, sardis_get_withdrawal_status
+
+**Approval**: sardis_request_approval, sardis_get_approval_status
+
+**Analytics**: sardis_get_spending_summary, sardis_get_spending_by_vendor, sardis_get_spending_by_category
+
+## Support
+
+- Documentation: https://docs.sardis.network
+- GitHub Issues: https://github.com/sardis-network/sardis/issues
+- Email: support@sardis.network

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sardis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,375 @@
+# @sardis/mcp-server
+
+[![npm version](https://img.shields.io/npm/v/@sardis/mcp-server.svg)](https://www.npmjs.com/package/@sardis/mcp-server)
+[![npm downloads](https://img.shields.io/npm/dm/@sardis/mcp-server.svg)](https://www.npmjs.com/package/@sardis/mcp-server)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+> Model Context Protocol (MCP) server for Sardis - Enable AI agents to execute secure payments with Financial Hallucination Prevention
+
+## Table of Contents
+
+- [Quick Start](#quick-start)
+- [What is this?](#what-is-this)
+- [Installation](#installation)
+- [Available Tools](#available-tools-36-total)
+- [Policy Engine](#policy-engine)
+- [Example Session](#example-session)
+- [Environment Variables](#environment-variables)
+- [Simulated Mode](#simulated-mode)
+- [API Reference](#api-reference)
+- [License](#license)
+
+## Quick Start
+
+```bash
+npx @sardis/mcp-server start
+```
+
+## What is this?
+
+Sardis MCP Server allows AI agents (Claude, Cursor, etc.) to execute payments through your Sardis wallet using the Model Context Protocol. It provides **Financial Hallucination Prevention** through natural language spending policies.
+
+## Installation
+
+### Option 1: npx (Recommended)
+
+No installation required - run directly:
+
+```bash
+npx @sardis/mcp-server start
+```
+
+### Option 2: Global Install
+
+```bash
+npm install -g @sardis/mcp-server
+sardis-mcp start
+```
+
+### Option 3: Local Install
+
+```bash
+npm install @sardis/mcp-server
+npx sardis-mcp start
+```
+
+## Configuration
+
+### Claude Desktop
+
+Add to your Claude Desktop configuration file:
+
+**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+**Linux**: `~/.config/Claude/claude_desktop_config.json`
+
+#### Minimal Configuration (Simulated Mode)
+
+```json
+{
+  "mcpServers": {
+    "sardis": {
+      "command": "npx",
+      "args": ["@sardis/mcp-server", "start"]
+    }
+  }
+}
+```
+
+#### Production Configuration
+
+```json
+{
+  "mcpServers": {
+    "sardis": {
+      "command": "npx",
+      "args": ["@sardis/mcp-server", "start"],
+      "env": {
+        "SARDIS_API_KEY": "sk_live_your_api_key_here",
+        "SARDIS_WALLET_ID": "wal_your_wallet_id",
+        "SARDIS_MODE": "live"
+      }
+    }
+  }
+}
+```
+
+### Cursor
+
+Add to your Cursor MCP settings (`.cursor/mcp.json` or Cursor settings):
+
+#### Minimal Configuration
+
+```json
+{
+  "mcpServers": {
+    "sardis": {
+      "command": "npx",
+      "args": ["@sardis/mcp-server", "start"]
+    }
+  }
+}
+```
+
+#### Production Configuration
+
+```json
+{
+  "mcpServers": {
+    "sardis": {
+      "command": "npx",
+      "args": ["@sardis/mcp-server", "start"],
+      "env": {
+        "SARDIS_API_KEY": "sk_live_your_api_key_here",
+        "SARDIS_WALLET_ID": "wal_your_wallet_id",
+        "SARDIS_MODE": "live"
+      }
+    }
+  }
+}
+```
+
+### Other MCP Clients
+
+For any MCP-compatible client, use:
+
+- **Command**: `npx`
+- **Arguments**: `["@sardis/mcp-server", "start"]`
+- **Transport**: `stdio`
+
+## Available Tools (36 total)
+
+### Wallet Tools (5)
+
+| Tool | Description |
+|------|-------------|
+| `sardis_get_wallet` | Get wallet details and configuration |
+| `sardis_get_balance` | Get current wallet balance and spending limits |
+| `sardis_create_wallet` | Create a new MPC wallet with optional spending policy |
+| `sardis_update_wallet_policy` | Update the spending policy for a wallet |
+| `sardis_list_wallets` | List all wallets, optionally filtered by agent or status |
+
+### Payment Tools (3)
+
+| Tool | Description |
+|------|-------------|
+| `sardis_pay` | Execute a secure payment with policy validation |
+| `sardis_get_transaction` | Get transaction status and details |
+| `sardis_list_transactions` | List recent transactions for a wallet |
+
+### Policy Tools (3)
+
+| Tool | Description |
+|------|-------------|
+| `sardis_check_policy` | Check if a payment would be allowed before executing |
+| `sardis_validate_limits` | Validate spending against daily/monthly limits |
+| `sardis_check_compliance` | Check vendor against compliance rules |
+
+### Hold Tools (6)
+
+| Tool | Description |
+|------|-------------|
+| `sardis_create_hold` | Create a pre-authorization hold on funds |
+| `sardis_capture_hold` | Capture a previously created hold |
+| `sardis_void_hold` | Void/cancel a hold without capturing |
+| `sardis_get_hold` | Get hold status and details |
+| `sardis_list_holds` | List active holds for a wallet |
+| `sardis_extend_hold` | Extend the expiration of a hold |
+
+### Agent Tools (4)
+
+| Tool | Description |
+|------|-------------|
+| `sardis_create_agent` | Create a new AI agent with identity |
+| `sardis_get_agent` | Get agent details and capabilities |
+| `sardis_list_agents` | List all agents in the organization |
+| `sardis_update_agent` | Update agent configuration |
+
+### Card Tools (6)
+
+| Tool | Description |
+|------|-------------|
+| `sardis_issue_card` | Issue a virtual card linked to a wallet |
+| `sardis_get_card` | Get virtual card details (masked) |
+| `sardis_list_cards` | List all virtual cards for a wallet |
+| `sardis_freeze_card` | Temporarily freeze a virtual card |
+| `sardis_unfreeze_card` | Unfreeze a previously frozen card |
+| `sardis_cancel_card` | Permanently cancel a virtual card |
+
+### Fiat Tools (4)
+
+| Tool | Description |
+|------|-------------|
+| `sardis_fund_wallet` | Fund a wallet from bank account, wire, or card |
+| `sardis_withdraw_to_bank` | Withdraw funds to a bank account |
+| `sardis_get_funding_status` | Check status of a funding transfer |
+| `sardis_get_withdrawal_status` | Check status of a withdrawal |
+
+### Approval Tools (2)
+
+| Tool | Description |
+|------|-------------|
+| `sardis_request_approval` | Request human approval for payments exceeding limits |
+| `sardis_get_approval_status` | Check status of a pending approval request |
+
+### Spending Analytics Tools (3)
+
+| Tool | Description |
+|------|-------------|
+| `sardis_get_spending_summary` | Get spending summary with totals and limits |
+| `sardis_get_spending_by_vendor` | Get spending breakdown by vendor |
+| `sardis_get_spending_by_category` | Get spending breakdown by category |
+
+## Policy Engine
+
+The server validates all payments against your configured spending policy:
+
+- **Allowed Categories**: SaaS, DevTools, Cloud, API
+- **Blocked Merchants**: Configurable blocklist
+- **Transaction Limits**: Max per transaction and daily limits
+- **Risk Scoring**: Each request gets a risk score
+- **Approval Workflows**: Human-in-the-loop for high-value transactions
+
+## Example Session
+
+```
+Agent: I need to pay $20 for OpenAI API credits
+
+[sardis_pay] vendor="OpenAI", amount=20, purpose="API Credits"
+
+Result: {
+  "success": true,
+  "status": "APPROVED",
+  "card": {
+    "number": "4242 **** **** 9999",
+    "cvv": "847",
+    "expiry": "12/26"
+  }
+}
+
+Agent: Can I buy a $500 Amazon gift card?
+
+[sardis_pay] vendor="Amazon", amount=500
+
+Result: {
+  "success": false,
+  "status": "BLOCKED",
+  "error": "POLICY_VIOLATION",
+  "message": "Merchant \"Amazon\" is not in the approved vendor list",
+  "prevention": "Financial Hallucination PREVENTED"
+}
+
+Agent: What's my spending this month?
+
+[sardis_get_spending_summary] period="month"
+
+Result: {
+  "total_spent": "450.00",
+  "transaction_count": 12,
+  "remaining_daily_limit": "50.00",
+  "remaining_monthly_limit": "550.00",
+  "top_vendor": "OpenAI"
+}
+```
+
+## Environment Variables
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `SARDIS_API_KEY` | No | - | Your Sardis API key. Get one at [sardis.network](https://sardis.network) |
+| `SARDIS_WALLET_ID` | No | - | Default wallet ID for operations |
+| `SARDIS_AGENT_ID` | No | - | Agent ID for this MCP connection |
+| `SARDIS_MODE` | No | `simulated` | `live` for real transactions, `simulated` for testing |
+| `SARDIS_API_URL` | No | `https://api.sardis.network` | API endpoint (for enterprise/self-hosted) |
+
+### Getting Your API Key
+
+1. Sign up at [sardis.network](https://sardis.network)
+2. Go to Settings > API Keys
+3. Create a new API key with appropriate permissions
+4. Add it to your MCP configuration
+
+## Simulated Mode
+
+When running without an API key, the server operates in simulated mode with:
+- Mock wallet with $1000 balance
+- Simulated transactions that don't execute on-chain
+- Full policy validation to test your rules
+- Realistic response formats
+
+## API Reference
+
+### Tools Schema
+
+Each tool follows the MCP tool specification:
+
+```typescript
+interface Tool {
+  name: string;
+  description: string;
+  inputSchema: JSONSchema;
+}
+```
+
+### Common Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `wallet_id` | `string` | The wallet ID to operate on |
+| `amount` | `string` | Amount in USD (e.g., "100.00") |
+| `vendor` | `string` | Merchant/vendor name |
+| `purpose` | `string` | Description of the payment purpose |
+
+### Response Format
+
+All tools return responses in this format:
+
+```typescript
+interface ToolResponse {
+  success: boolean;
+  status: 'APPROVED' | 'BLOCKED' | 'PENDING' | 'ERROR';
+  data?: Record<string, unknown>;
+  error?: string;
+  message?: string;
+}
+```
+
+## Requirements
+
+- Node.js 18.0.0 or higher
+- Claude Desktop, Cursor, or any MCP-compatible client
+
+## Troubleshooting
+
+### Server not starting
+
+1. Ensure Node.js 18+ is installed: `node --version`
+2. Clear npx cache: `npx clear-npx-cache`
+3. Try global install: `npm install -g @sardis/mcp-server`
+
+### Tools not appearing in Claude
+
+1. Restart Claude Desktop after configuration changes
+2. Check the configuration file path is correct for your OS
+3. Verify JSON syntax is valid
+
+### API errors
+
+1. Check your API key is valid
+2. Ensure `SARDIS_MODE` is set to `live` for production
+3. Verify wallet ID exists in your account
+
+## Support
+
+- [Documentation](https://docs.sardis.network)
+- [GitHub Issues](https://github.com/sardis-network/sardis/issues)
+- [Discord Community](https://discord.gg/sardis)
+- Email: support@sardis.network
+
+## Contributing
+
+See [CONTRIBUTING.md](../../CONTRIBUTING.md) for guidelines.
+
+## License
+
+MIT - see [LICENSE](./LICENSE) for details.

package/dist/api.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Sardis API Client for MCP Server
+ *
+ * Handles all API communication with the Sardis backend.
+ */
+/**
+ * Make an API request to Sardis
+ */
+export declare function apiRequest<T>(method: string, path: string, body?: unknown): Promise<T>;
+/**
+ * Generate unique mandate ID
+ *
+ * SECURITY: Uses crypto.randomUUID() for cryptographically secure IDs.
+ * Math.random() is not suitable for security-relevant identifiers.
+ */
+export declare function generateMandateId(): string;
+/**
+ * Create SHA-256 hash for audit
+ *
+ * SECURITY: The fallback now uses Node.js crypto module instead of a
+ * predictable timestamp string. Audit hashes must provide collision
+ * resistance for financial integrity.
+ */
+export declare function createAuditHash(data: string): Promise<string>;
+//# sourceMappingURL=api.d.ts.map

package/dist/api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH;;GAEG;AACH,wBAAsB,UAAU,CAAC,CAAC,EAChC,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,IAAI,CAAC,EAAE,OAAO,GACb,OAAO,CAAC,CAAC,CAAC,CAsBZ;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAS1C;AAED;;;;;;GAMG;AACH,wBAAsB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAmBnE"}