Skip to main content

What It Is

@nuwa-ai/cap-kit helps you register, discover, and manage Caps (Agent Capability Packages). It integrates DID auth, IPFS storage, Rooch contracts, and MCP.

Examples

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

const env = await TestEnv.bootstrap({ rpcUrl: 'https://test-seed.rooch.network', network: 'test' });
const { signer, did } = await createSelfDid(env);

const capKit = new CapKit({ roochUrl: 'https://test-seed.rooch.network', mcpUrl: 'https://<your-mcp-server>', contractAddress: '<contract>', signer });

await capKit.registerCap({
  authorDID: did,
  idName: 'my_awesome_cap',
  core: {
    prompt: { value: 'You are...' },
    model: { providerId: 'openrouter', modelId: 'openai/gpt-4o-mini', supportedInputs: ['text'], contextLength: 128000 },
    mcpServers: { tools: 'https://<your-mcp-server>' },
  },
  metadata: { displayName: 'Awesome Cap', description: '...', introduction: '...', tags: ['demo'] },
});
Query & Stats
const result = await capKit.queryByName('translator', { page: 1, size: 20, sortBy: 'downloads' });
const byId = await capKit.queryByID({ id: 'did:rooch:0x..:translator' });
const cap = await capKit.downloadByCID('bafybei...');
const stats = await capKit.queryCapStats(cap.id);
await capKit.favorite(cap.id, 'add');

Install

pnpm add @nuwa-ai/cap-kit @nuwa-ai/identity-kit

CapKit (Constructor)

Create a CapKit client. Inputs
options
object
required
Returns
capKit
CapKit
Configured CapKit instance

Methods

getTools

Fetch and cache MCP tool registry. Inputs
(none)
void
No input parameters
Returns
tools
record
Server-exposed tools keyed by name

mcpClose

Close the underlying MCP client. Inputs
(none)
void
No input parameters
Returns
result
void
No return value

queryByID

Query Cap metadata by id or cid. Inputs
id
string?
Cap id (e.g., did:…:name)
cid
string?
IPFS CID
Returns
result
Result<ResultCap>
Result wrapper with code, data?, error?

queryByName

Search Caps by name/tags with pagination/sort. Inputs
name
string?
Optional partial name
tags
string[]?
Filter by tags
page
number?
Page index
size
number?
Page size
sortBy
"average_rating"|"downloads"|"favorites"|"rating_count"|"updated_at"?
Sort field
sortOrder
"asc"|"desc"?
Sort order
Returns
result
Result<Page<ResultCap>>
Paged results

queryMyFavorite

List favorite Caps of the current DID. Inputs
page
number?
Page index
size
number?
Page size
Returns
result
Result<Page<ResultCap>>
Paged favorites

favorite

Add/remove/check favorite for a Cap. Inputs
capId
string
required
Cap identifier
action
"add"|"remove"|"isFavorite"
required
Operation to perform
Returns
result
Result<boolean>
True on success

queryCapStats

Fetch downloads/ratings/favorites. Inputs
capId
string
required
Cap identifier
Returns
result
Result<CapStats>
Stats including downloads, averages, favorites

rateCap

Rate a Cap (1..5). Inputs
capId
string
required
Cap identifier
rating
number
required
Integer 1..5
Returns
result
Result<boolean>
True on success

queryCapRatingDistribution

Get rating histogram for a Cap. Inputs
capId
string
required
Cap identifier
Returns
result
Result<RatingDistribution[]>
Distribution list

updateEnableCap

Enable/disable a Cap. Inputs
capId
string
required
Cap identifier
action
"enable"|"disable"
required
Toggle action
Returns
result
Result<boolean>
True on success

downloadByID / downloadByCID

Download Cap YAML via id/cid and parse into Cap. Inputs
id | cid
string
required
Cap id or IPFS CID
format
"base64"|"utf8"?
Optional format
Returns
cap
Cap
Parsed Cap object

registerCap

Upload Cap YAML to IPFS and register on-chain. Inputs
cap
Cap
required
Cap content to register
Returns
cid
string
IPFS CID