@kya-os/mcp-i v0.1.0-alpha.3.6

@kya-os/mcp-i

The SEO package for AI agents. Register your MCP server and get automatic directory listings in 2 lines of code.

Note: This package is alpha release, do not use in production. v1.0.0 will be released this week.

Why Your MCP Server Needs This

For MCP Server Developers:

• Get a DID - Your agent gets a permanent, cryptographic identity from knowthat.ai
• Automatic Directory Listings - Submit to multiple directories with zero extra work
• Build Reputation - Every interaction is signed and verifiable
• Future-Proof - Ready for the decentralized agent ecosystem
• Production-Ready - Optimized for Lambda, Edge, Next.js, and traditional deployments

For Directory Maintainers:

• Easy Integration - List MCP-I compliant agents automatically
• Verified Agents - Only list agents with cryptographic proof
• Join the Network - Tap into the growing MCP-I ecosystem

How It Works

1. Identity Registration: Your agent is registered with knowthat.ai (the MCP-I registry)
2. DID Generation: You get a did:web:knowthat.ai:agents:your-agent identifier
3. Directory Submission: Based on your preferences, knowthat.ai submits your agent to directories
4. Cryptographic Signing: All agent responses are signed with your private key
5. Verification: Anyone can verify your agent's identity and authenticity

Installation

npm install @kya-os/mcp-i

Quick Start

1. Zero Configuration (Recommended)

import "@kya-os/mcp-i/auto";
// That's it! Your server now has cryptographic identity

2. Production Configuration

import { enableMCPIdentity } from "@kya-os/mcp-i";

const identity = await enableMCPIdentity({
  name: "Production Agent",

  // Auto-detect runtime (Lambda, Edge, Node.js)
  storage: "auto",
  transport: "auto",

  // Encrypt private keys at rest
  encryptionPassword: process.env.AGENT_KEY_PASSWORD,

  // Professional logging
  logLevel: "error", // or 'silent' for production

  // Directory preferences (optional)
  directories: "verified", // List on all verified directories
  // OR directories: ["smithery", "glama"] // Specific directories
  // OR directories: "none" // No directory listings
});

// Enable automatic key rotation
await identity.enableAutoRotation({
  maxAge: 90 * 24 * 60 * 60 * 1000, // 90 days
  maxSignatures: 1_000_000, // 1M signatures
});

3. Lambda/Edge Runtime

// Automatic configuration for serverless
const identity = await enableMCPIdentity({
  name: "Serverless Agent",
  storage: "memory", // No file system needed
  transport: "fetch", // Native fetch for edge
  logLevel: "silent", // No console output
});

Production Features

Performance Optimizations

• Lazy Loading: Crypto libraries load only when needed
• Signature Caching: Repeated signatures are 10x faster
• Precomputed Values: DIDs and keys cached in memory
• Optimized Transport: Auto-selects axios vs fetch

Security Features

• Key Encryption: Private keys encrypted with AES-256-GCM
• Key Rotation: Automatic rotation based on age/usage
• Nonce Tracking: Prevents replay attacks
• Timestamp Validation: Configurable tolerance windows

Runtime Support

• AWS Lambda: Automatic memory storage
• Vercel Edge: Native fetch transport
• Cloudflare Workers: Full compatibility
• Node.js: Traditional file storage

Directory Listings

// Configure directory listings
await enableMCPIdentity({
  name: "My Agent",

  // Option 1: List on all verified directories
  directories: "verified",

  // Option 2: List on specific directories
  directories: ["smithery", "glama"],

  // Option 3: No directory listings (registry only)
  directories: "none",
});

// Directory preferences are sent to knowthat.ai
// The registry handles submissions to your chosen directories

Advanced Usage

Key Rotation

// Check key health
const health = identity.checkKeyHealth();
console.log(`Key age: ${health.age}ms`);
console.log(`Signatures: ${health.signatureCount}`);
console.log(`Should rotate: ${health.shouldRotate}`);

// Manual rotation
const result = await identity.rotateKeys("security-policy");
if (result.success) {
  console.log(`Grace period ends: ${result.gracePeriodEnd}`);
}

// Automatic rotation
await identity.enableAutoRotation({
  maxAge: 30 * 24 * 60 * 60 * 1000, // 30 days
  maxSignatures: 500_000, // 500k signatures
});

Edit/Claim URLs

// Get signed URLs for editing
const { editUrl, claimUrl } = await identity.requestEditAccess();

// Edit URL - for existing agents
console.log("Edit your agent:", editUrl);

// Claim URL - for draft/unclaimed agents
console.log("Claim your agent:", claimUrl);

Custom Storage

// Encrypted file storage
await enableMCPIdentity({
  storage: "file",
  persistencePath: "/secure/location/.identity",
  encryptionPassword: "strong-password",
});

// Memory storage with custom key
await enableMCPIdentity({
  storage: "memory",
  memoryKey: "agent-123", // Useful for multiple agents
});

Custom Logger

await enableMCPIdentity({
  logger: {
    debug: (msg, ...args) => myLogger.debug(msg, args),
    info: (msg, ...args) => myLogger.info(msg, args),
    warn: (msg, ...args) => myLogger.warn(msg, args),
    error: (msg, ...args) => myLogger.error(msg, args),
  },
});

API Reference

enableMCPIdentity(options?)

Main function to enable identity for your MCP server.

Options:

interface MCPIdentityOptions {
  // Basic info
  name?: string;
  description?: string;
  repository?: string;

  // Storage
  storage?: "file" | "memory" | "auto";
  persistencePath?: string;
  memoryKey?: string;
  encryptionPassword?: string;

  // Transport
  transport?: "axios" | "fetch" | "auto";

  // Security
  timestampTolerance?: number; // Default: 60000ms
  enableNonceTracking?: boolean; // Default: true

  // Directory listings
  directories?: string[] | "verified" | "none"; // Default: "verified"

  // Development
  mode?: "development" | "production";

  // Logging
  logger?: Logger;
  logLevel?: "debug" | "info" | "warn" | "error" | "silent";
}

MCPIdentity Methods

• sign(message): Sign with caching
• verify(message, signature, publicKey?): Verify signatures
• respondToChallenge(challenge): MCP-I authentication
• signResponse(response): Add identity to responses
• requestEditAccess(): Get edit/claim URLs
• rotateKeys(reason?): Manual key rotation
• enableAutoRotation(policy?): Automatic rotation
• checkKeyHealth(): Key rotation status

Files Created

.mcp-identity.json    # Your agent's identity (encrypted if password set)

Security Best Practices

1. Use encryption in production: Always set encryptionPassword
2. Enable key rotation: Set up automatic rotation policies
3. Secure storage: Use appropriate file permissions
4. Monitor key health: Check rotation status regularly
5. Add to .gitignore: Never commit identity files

Performance Tips

1. Use memory storage for Lambda/Edge runtimes
2. Enable signature caching (automatic)
3. Use 'silent' log level in production
4. Let transport auto-select based on runtime
5. Preload identity during cold starts

Troubleshooting

Lambda/Edge Issues

• Ensure storage: 'memory' or 'auto'
• Use transport: 'fetch' for edge runtimes
• Set logLevel: 'silent' to avoid console issues

Key Rotation Failures

• Check network connectivity to knowthat.ai
• Verify current keys are not corrupted
• Manual rotation: await identity.rotateKeys('recovery')

Performance Issues

• Verify signature caching is working
• Check lazy loading (should see delayed first signature)
• Use memory storage when possible

License

MIT