Skip to content

MCP_TOOL_SPECIFICATION.md

Latest commit

 

History

History
270 lines (178 loc) · 8.69 KB

MCP_TOOL_SPECIFICATION.md

File metadata and controls

270 lines (178 loc) · 8.69 KB

Wallet - MCP Tool Specification

General Considerations for Wallet Tools

  • Dependencies: All tools require the encryption module (for KeyManager) and logging_monitoring module.
  • Initialization: WalletManager must be instantiated before tool invocation. Key storage directory should be configured.
  • Error Handling: Errors are logged via logging_monitoring. Tools return {"error": "description"} on failure.
  • Security: Private keys are never exposed in tool outputs. Only hashes and metadata are returned.

Tool: wallet_create

1. Tool Purpose and Description

Creates a new self-custody wallet for a specified user. Generates a wallet address and securely stores the private key via the encryption module's KeyManager.

2. Invocation Name

wallet_create

3. Input Schema (Parameters)

Parameter Name Type Required Description Example Value
user_id string Yes Unique identifier for wallet owner "agent_001"
storage_path string No Key storage directory path "/tmp/keys"

4. Output Schema (Return Value)

Field Name Type Description Example Value
wallet_address string Generated 0x-prefixed address "0x1a2b3c4d5e6f..."
user_id string Owner user ID "agent_001"
status string Operation result "success"

5. Error Handling

  • WALLET_EXISTS: User already has a wallet.
  • KEY_STORAGE_FAILED: Key could not be persisted.

6. Idempotency

  • Idempotent: No. Each call creates a new wallet. Calling for an existing user raises an error.

7. Usage Examples

{
  "tool_name": "wallet_create",
  "arguments": {
    "user_id": "agent_001"
  }
}

8. Security Considerations

  • Input Validation: user_id is validated as non-empty string.
  • Data Handling: Private keys are stored with 0o600 permissions. Never returned in output.
  • Permissions: Requires write access to key storage directory.

Tool: wallet_sign

1. Tool Purpose and Description

Signs a message using the user's wallet private key via HMAC-SHA256.

2. Invocation Name

wallet_sign

3. Input Schema (Parameters)

Parameter Name Type Required Description Example Value
user_id string Yes Wallet owner user ID "agent_001"
message string Yes Base64-encoded message "SGVsbG8gV29ybGQ="

4. Output Schema (Return Value)

Field Name Type Description Example Value
signature string Base64-encoded HMAC signature "a1b2c3d4e5f6..."
status string Operation result "success"

5. Error Handling

  • WALLET_NOT_FOUND: No wallet exists for user.
  • KEY_LOCKED: Key retrieval failed.

6. Idempotency

  • Idempotent: Yes. Same input always produces the same signature.

7. Usage Examples

{
  "tool_name": "wallet_sign",
  "arguments": {
    "user_id": "agent_001",
    "message": "SGVsbG8gV29ybGQ="
  }
}

8. Security Considerations

  • Data Handling: Private key is used in-memory only, never logged or returned.
  • Output Sanitization: Only the signature is returned, not the key.

Tool: wallet_rotate_keys

1. Tool Purpose and Description

Rotates the private key for a user's wallet. Generates new key material and wallet address.

2. Invocation Name

wallet_rotate_keys

3. Input Schema (Parameters)

Parameter Name Type Required Description Example Value
user_id string Yes Wallet owner user ID "agent_001"
reason string No Rotation reason "policy"

4. Output Schema (Return Value)

Field Name Type Description Example Value
new_wallet_address string New wallet address "0xaa11bb22..."
reason string Rotation reason "policy"
status string Operation result "success"

5. Error Handling

  • WALLET_NOT_FOUND: User has no wallet.
  • KEY_STORAGE_FAILED: New key could not be stored.

6. Idempotency

  • Idempotent: No. Each call generates new key material.

7. Usage Examples

{
  "tool_name": "wallet_rotate_keys",
  "arguments": {
    "user_id": "agent_001",
    "reason": "scheduled"
  }
}

8. Security Considerations

  • Data Handling: Old key material is overwritten. New key stored with 0o600 permissions.

Tool: wallet_backup

1. Tool Purpose and Description

Creates an encrypted backup snapshot of a user's wallet metadata. Returns hashes and metadata only.

2. Invocation Name

wallet_backup

3. Input Schema (Parameters)

Parameter Name Type Required Description Example Value
user_id string Yes Wallet owner user ID "agent_001"

4. Output Schema (Return Value)

Field Name Type Description Example Value
wallet_id string Wallet address "0x1a2b3c..."
key_hash string SHA-256 hash of key "e3b0c44298fc1c14..."
backup_ts string ISO 8601 timestamp "2026-02-04T12:00:00+00:00"
status string Operation result "success"

5. Error Handling

  • WALLET_NOT_FOUND: User has no wallet.

6. Idempotency

  • Idempotent: Partially. Same key produces same hash, but timestamp differs.

7. Usage Examples

{
  "tool_name": "wallet_backup",
  "arguments": {
    "user_id": "agent_001"
  }
}

8. Security Considerations

  • Data Handling: Only key hash is returned, never raw key material.
  • File Paths: Backup files stored with 0o600 permissions in designated backup directory.

Tool: wallet_recover

1. Tool Purpose and Description

Attempts Natural Ritual recovery by verifying a sequence of secret knowledge responses.

2. Invocation Name

wallet_recover

3. Input Schema (Parameters)

Parameter Name Type Required Description Example Value
user_id string Yes User attempting recovery "agent_001"
responses array[string] Yes Answers to ritual prompts ["Red", "Cat"]

4. Output Schema (Return Value)

Field Name Type Description Example Value
recovered boolean Whether recovery succeeded true
remaining_attempts integer Attempts left before lockout 3
status string Operation result "success"

5. Error Handling

  • NO_RITUAL: No ritual registered for user.
  • LOCKED_OUT: User has exhausted all recovery attempts.

6. Idempotency

  • Idempotent: No. Each call consumes an attempt on failure.

7. Usage Examples

{
  "tool_name": "wallet_recover",
  "arguments": {
    "user_id": "agent_001",
    "responses": ["MySecretColor", "MySecretAnimal"]
  }
}

8. Security Considerations

  • Input Validation: Responses are hashed immediately, never stored in plaintext.
  • Rate Limiting: Built-in lockout after configurable number of failed attempts (default: 5).
  • Data Handling: Failed attempt details are logged but do not reveal which step failed to the caller.