Cap Kit

About Nuwa Cap Kit

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

Show options

mcpUrl · string · required

MCP host that provides cap-store tools

roochUrl · string · required

Rooch RPC endpoint

contractAddress · string · required

Cap registry contract address

signer · SignerInterface · required

DID signer used to sign on-chain txs

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