@nuwa-ai/cap-kit

A TypeScript library for managing Agent Capability Packages (ACPs) on the Nuwa Protocol. This library provides seamless integration between Web3 identity authentication, IPFS storage, and blockchain contracts for decentralized AI agent capability management.

Features

• 🔐 DID-based Authentication: Secure identity management using Decentralized Identifiers
• 🌐 IPFS Storage: Decentralized file storage for capability packages
• ⛓️ Blockchain Integration: On-chain registration using Rooch blockchain
• 🤖 MCP Protocol: Model Context Protocol integration for AI agent communication
• 🔍 Query & Discovery: Efficient capability package search and retrieval
• 📦 TypeScript Support: Full TypeScript support with comprehensive type definitions

Installation

npm install @nuwa-ai/cap-kit

or

yarn add @nuwa-ai/cap-kit

Quick Start

import { CapKit } from '@nuwa-ai/cap-kit';
import { createSelfDid, TestEnv } from '@nuwa-ai/identity-kit';

// Initialize the environment
const env = await TestEnv.bootstrap({
  rpcUrl: 'https://test-seed.rooch.network',
  network: 'test',
  debug: false,
});

// Create a DID signer
const { signer } = await createSelfDid(env, {
  customScopes: ['0xcontract::*::*']
});

// Initialize CapKit
const capKit = new CapKit({
  roochUrl: 'https://test-seed.rooch.network',
  mcpUrl: 'https://nuwa-production-a276.up.railway.app',
  contractAddress: '0xdc2a3eba923548660bb642b9df42936941a03e2d8bab223ae6dda6318716e742',
  signer,
});

// Register a new capability
const cid = await capKit.registerCap(
  'my_awesome_cap',
  'Description of my capability',
  {
    version: '1.0.0',
    capabilities: ['text-generation', 'summarization']
  }
);

console.log(`Capability registered with CID: ${cid}`);

API Reference

Constructor

new CapKit(options: {
  mcpUrl: string;
  roochUrl: string;
  contractAddress: string;
  signer: SignerInterface;
})

• mcpUrl: URL of the MCP server for IPFS operations
• roochUrl: URL of the Rooch blockchain RPC endpoint
• contractAddress: Address of the ACP registry smart contract
• signer: DID-based signer for authentication

Methods

registerCap(name, description, options)

Registers a new Agent Capability Package.

async registerCap(
  name: string,
  description: string,
  options: any
): Promise<string>

Parameters:

• name: Unique capability name (6-20 characters, alphanumeric and underscore only)
• description: Human-readable description of the capability
• options: Additional metadata and configuration

Returns: IPFS CID of the registered capability package

Example:

const cid = await capKit.registerCap(
  'web_scraper',
  'Advanced web scraping capability with rate limiting',
  {
    version: '2.1.0',
    capabilities: ['web-scraping', 'data-extraction'],
    requirements: {
      memory: '512MB',
      permissions: ['network-access']
    }
  }
);

queryCapWithCID(cid)

Retrieves capability metadata by IPFS CID.

async queryCapWithCID(cid: string): Promise<any>

Parameters:

• cid: IPFS Content Identifier

Returns: Capability metadata object

Example:

const capability = await capKit.queryCapWithCID('QmcG8y4tGQacqSMJdWUQuJvf4921psvoasfQrasMRRTC3q');
console.log(capability.name, capability.description);

queryWithName(name?, page?, size?)

Searches capabilities by name with pagination support.

async queryWithName(
  name?: string,
  page?: number,
  size?: number
): Promise<any>

Parameters:

• name: Optional name filter for search
• page: Page number for pagination (default: 1)
• size: Number of results per page (default: 10)

Returns: Paginated list of capability packages

Example:

// Search all capabilities
const allCaps = await capKit.queryWithName();

// Search by name with pagination
const results = await capKit.queryWithName('web', 1, 20);
console.log(`Found ${results.total} capabilities`);

downloadCap(cid, format?)

Downloads the content of a capability package.

async downloadCap(
  cid: string, 
  format?: 'base64' | 'utf8'
): Promise<any>

Parameters:

• cid: IPFS Content Identifier
• format: Data format for download (default: 'utf8')

Returns: Downloaded capability package content

Example:

const content = await capKit.downloadCap(
  'QmcG8y4tGQacqSMJdWUQuJvf4921psvoasfQrasMRRTC3q',
  'utf8'
);

// Parse YAML content
import * as yaml from 'js-yaml';
const capability = yaml.load(content.data.fileData);

Configuration

Environment Setup

For development and testing, you can use different network configurations:

// Local development
const capKit = new CapKit({
  roochUrl: 'http://localhost:6767',
  mcpUrl: 'http://localhost:3000/mcp',
  contractAddress: '0xlocal_contract_address',
  signer,
});

// Testnet
const capKit = new CapKit({
  roochUrl: 'https://test-seed.rooch.network',
  mcpUrl: 'https://nuwa-production-a276.up.railway.app',
  contractAddress: '0xdc2a3eba923548660bb642b9df42936941a03e2d8bab223ae6dda6318716e742',
  signer,
});

Capability Package Format

Capability packages are stored as YAML files with the following structure:

id: "did:nuwa:user123:my_capability"
name: "my_capability"
description: "Description of the capability"
version: "1.0.0"
capabilities:
  - "text-generation"
  - "data-analysis"
requirements:
  memory: "256MB"
  permissions:
    - "network-access"
    - "file-system-read"
metadata:
  author: "User Name"
  license: "MIT"
  tags: ["ai", "nlp", "utility"]

Error Handling

The library includes comprehensive error handling for common scenarios:

try {
  const cid = await capKit.registerCap('test_cap', 'Test capability', {});
} catch (error) {
  if (error.message.includes('Name must be between 6 and 20 characters')) {
    console.error('Invalid capability name format');
  } else if (error.message.includes('Upload failed')) {
    console.error('IPFS upload error:', error.message);
  } else {
    console.error('Registration failed:', error.message);
  }
}

Development

Running Tests

npm run test

Building

npm run build

Linting

npm run lint

Dependencies

• @nuwa-ai/identity-kit: DID-based identity management
• @roochnetwork/rooch-sdk: Rooch blockchain integration
• @modelcontextprotocol/sdk: Model Context Protocol client
• js-yaml: YAML parsing and serialization
• ai: AI SDK for MCP client creation

Contributing

We welcome contributions! Please see our Contributing Guide for details.

License

This project is licensed under the Apache-2.0 License - see the LICENSE file for details.

Support

• GitHub Issues
• Documentation
• Nuwa Protocol