@kya-os/mcp-i 0.1.0-alpha.2.3 → 0.1.0-alpha.2.5

package/README.md

@@ -1,6 +1,6 @@
 # @kya-os/mcp-i
 
-Give your MCP server a decentralized identity (DID) in 2 lines of code. Build reputation, enable discovery, and future-proof your agent for the emerging identity ecosystem.
+The SEO package for AI agents. Register your MCP server and get automatic directory listings in 2 lines of code.
 
 [![npm version](https://img.shields.io/npm/v/@kya-os/mcp-i.svg)](https://www.npmjs.com/package/@kya-os/mcp-i)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
@@ -10,36 +10,25 @@ Give your MCP server a decentralized identity (DID) in 2 lines of code. Build re
 
 **For MCP Server Developers:**
 
-- 🆔 **Get a DID** - Your server gets a permanent, cryptographic identity
-- 📈 **Build Reputation** - Every interaction is signed and verifiable
-- 🔍 **Automatic Discovery** - Listed on registries as they adopt MCP-I
-- 🔮 **Future-Proof** - Ready for the decentralized agent ecosystem
+- **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** - Become an MCP-I registry with our SDK
-- ✅ **Verified Agents** - Only list agents with cryptographic proof
-- 🌐 **Join the Standard** - Be part of the emerging identity layer
+- **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
 
-## The Vision
+## How It Works
 
-Your AI agent needs identity to:
-
-- **Prove who it is** to other services (authentication)
-- **Be discovered** by users and other agents (visibility)
-- **Build reputation** through verified interactions (trust)
-- **Access APIs** that require identity verification (capability)
-
-## 🚨 IMPORTANT: API Call Behavior
-
-**This package is designed to be spam-free:**
-
-- **First run only**: API calls happen ONLY on first initialization
-- **Persistent identity**: After first run, loads from disk with ZERO API calls
-- **No spam on restarts**: Restart your server 1000 times = still zero API calls
-- **Rate limited**: Built-in protection against accidental registry spam
-
-[Read the full API behavior guide →](./API_BEHAVIOR.md)
+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
 
@@ -56,206 +45,159 @@ import "@kya-os/mcp-i/auto";
 // That's it! Your server now has cryptographic identity
 ```
 
-### 2. With Configuration
+### 2. Production Configuration
 
 ```typescript
 import { enableMCPIdentity } from "@kya-os/mcp-i";
 
-await enableMCPIdentity({
-  name: "Calendar Assistant",
-  description: "AI agent for professional calendar management",
-  repository: "https://github.com/your-org/calendar-assistant",
-});
-```
-
-## Current State & Roadmap
+const identity = await enableMCPIdentity({
+  name: "Production Agent",
 
-**Today:**
+  // Auto-detect runtime (Lambda, Edge, Node.js)
+  storage: "auto",
+  transport: "auto",
 
-- ✅ Your MCP server gets a DID (decentralized identifier)
-- ✅ Every response is cryptographically signed
-- ✅ Registered on KnowThat.ai registry
-- ✅ Full MCP-I Level 2 conformance
+  // Encrypt private keys at rest
+  encryptionPassword: process.env.AGENT_KEY_PASSWORD,
 
-**Coming Soon:**
+  // Professional logging
+  logLevel: "error", // or 'silent' for production
 
-- 🔜 Additional registry support as directories adopt MCP-I
-- 🔜 Cross-registry reputation aggregation
-- 🔜 Enhanced discovery features
-- 🔜 Agent-to-agent secure communication
-
-## What Happens Under the Hood
-
-When you import this package:
+  // Directory preferences (optional)
+  directories: "verified", // List on all verified directories
+  // OR directories: ["smithery", "glama"] // Specific directories
+  // OR directories: "none" // No directory listings
+});
 
-1. **First Run Only**:
+// Enable automatic key rotation
+await identity.enableAutoRotation({
+  maxAge: 90 * 24 * 60 * 60 * 1000, // 90 days
+  maxSignatures: 1_000_000, // 1M signatures
+});
+```
 
-   - Generates Ed25519 cryptographic keypair
-   - Registers with KnowThat.ai to obtain a DID
-   - Saves identity to `.mcp-identity.json`
-   - Total time: ~2 seconds
+### 3. Lambda/Edge Runtime
 
-2. **Every Subsequent Run**:
+```typescript
+// 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
+});
+```
 
-   - Loads existing identity from disk
-   - Zero API calls, instant startup
-   - Maintains the same DID forever
+## Production Features
 
-3. **During Operation**:
-   - Every response includes `_mcp_identity` field with cryptographic signature
-   - Handles MCP-I challenge-response authentication automatically
-   - Advertises identity capabilities to clients
+### Performance Optimizations
 
-## Example Response
+- **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
 
-After enabling MCP-I, all your server responses automatically include cryptographic signatures:
+### Security Features
 
-```json
-{
-  "content": [
-    {
-      "type": "text",
-      "text": "Meeting scheduled for tomorrow at 2 PM"
-    }
-  ],
-  "_mcp_identity": {
-    "did": "did:web:knowthat.ai:agents:calendar-assistant",
-    "signature": "0x3045...",
-    "timestamp": "2025-01-06T10:00:00Z",
-    "conformanceLevel": 2
-  }
-}
-```
+- **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
 
-## Advanced Configuration
+### Runtime Support
 
-### Registry Support (Future-Ready)
+- **AWS Lambda**: Automatic memory storage
+- **Vercel Edge**: Native fetch transport
+- **Cloudflare Workers**: Full compatibility
+- **Node.js**: Traditional file storage
 
-As more directories adopt MCP-I, your agent will automatically be discoverable across the ecosystem:
+### Directory Listings
 
 ```typescript
+// Configure directory listings
 await enableMCPIdentity({
   name: "My Agent",
-  registries: "verified", // default
-  // Currently registers with KnowThat.ai
-  // Additional registries will be supported as they adopt MCP-I
-});
-```
-
-**Note for Directory Maintainers:** Want to add your directory as a supported registry? [Contact us](https://github.com/orgs/modelcontextprotocol-identity/discussions/new?category=mcp-i-directories) to discuss integration.
 
-### Custom DID Host
+  // Option 1: List on all verified directories
+  directories: "verified",
 
-For enterprises who want to host their own DID:
+  // Option 2: List on specific directories
+  directories: ["smithery", "glama"],
 
-```typescript
-await enableMCPIdentity({
-  name: "Enterprise Agent",
-  didHost: "company.com", // Creates did:web:company.com:agents:...
+  // Option 3: No directory listings (registry only)
+  directories: "none",
 });
-```
 
-Note: The Agent's did must discoverable via company.com/.well-known/did.json
+// Directory preferences are sent to knowthat.ai
+// The registry handles submissions to your chosen directories
+```
 
-### Edit Your Agent Profile
+## Advanced Usage
 
-Only you can edit your agent's profile, thanks to cryptographic proof:
+### Key Rotation
 
 ```typescript
-const identity = await enableMCPIdentity();
+// 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}`);
+}
 
-// Get a signed edit URL
-const editUrl = await identity.requestEditAccess();
-console.log("Edit your agent at:", editUrl);
-// https://knowthat.ai/agents/edit?did=...&timestamp=...&signature=...
+// Automatic rotation
+await identity.enableAutoRotation({
+  maxAge: 30 * 24 * 60 * 60 * 1000, // 30 days
+  maxSignatures: 500_000, // 500k signatures
+});
 ```
 
-## Key Benefits
-
-**Immediate Benefits:**
-
-- 🛡️ **Cryptographic Identity**: Every response is signed with Ed25519
-- 🆔 **Permanent DID**: Your agent gets a decentralized identifier that you control
-- 🔐 **Impersonation Protection**: Nobody can pretend to be your agent
-- ✅ **Verification Ready**: Cryptographic proof of authenticity
+### Edit/Claim URLs
 
-**Future Benefits (as ecosystem grows):**
-
-- 🔍 **Multi-Registry Discovery**: Automatically listed as directories adopt MCP-I
-- 📈 **Reputation Building**: Verifiable interaction history across platforms
-- 🚀 **Priority Access**: Identity-aware APIs will offer higher rate limits
-- 🏆 **Trust Badges**: Stand out as an early adopter of decentralized identity
-
-## How MCP-I Works
+```typescript
+// Get signed URLs for editing
+const { editUrl, claimUrl } = await identity.requestEditAccess();
 
-```mermaid
-sequenceDiagram
-    participant User
-    participant Client as AI Client
-    participant Agent as Your MCP Server
-    participant API as Protected API
+// Edit URL - for existing agents
+console.log("Edit your agent:", editUrl);
 
-    User->>Client: "Book a meeting"
-    Client->>Agent: MCP request
-    Note over Agent: Signs response with private key
-    Agent->>Client: Response + _mcp_identity
-    Client->>API: Forward request with identity
-    API->>API: Verify signature
-    API->>Client: Authorized response
-    Client->>User: "Meeting booked!"
+// Claim URL - for draft/unclaimed agents
+console.log("Claim your agent:", claimUrl);
 ```
 
-## Files Created
-
-After initialization, you'll see these files in your project root:
+### Custom Storage
 
-```
-.mcp-identity.json    # Your agent's identity (⚠️ Contains private key!)
-```
+```typescript
+// Encrypted file storage
+await enableMCPIdentity({
+  storage: "file",
+  persistencePath: "/secure/location/.identity",
+  encryptionPassword: "strong-password",
+});
 
-The file contains:
-
-```json
-{
-  "did": "did:web:knowthat.ai:agents:your-agent",
-  "publicKey": "base64-encoded-public-key",
-  "privateKey": "base64-encoded-private-key", // Keep this secret!
-  "agentId": "uuid",
-  "agentSlug": "your-agent-slug",
-  "registeredAt": "2025-01-06T10:00:00Z",
-  "didHost": "knowthat.ai",
-  "registry": {
-    "name": "knowthat.ai",
-    "status": "active",
-    "url": "https://knowthat.ai/agents/your-agent-slug"
-  }
-}
+// Memory storage with custom key
+await enableMCPIdentity({
+  storage: "memory",
+  memoryKey: "agent-123", // Useful for multiple agents
+});
 ```
 
-## Security Best Practices
-
-- 🔐 **Private keys never leave your server** - stored locally only
-- ✍️ **Ed25519 signatures** - cryptographically secure
-- 🛡️ **Replay protection** - timestamps and nonces prevent attacks
-- 🔑 **Add `.mcp-identity.json` to .gitignore** - contains private key!
-
-## Troubleshooting
-
-### "Rate limit exceeded"
-
-- Wait 1 hour before retrying
-- Each IP can register 10 agents/hour on KnowThat.ai
-
-### Agent not showing as verified
-
-- Verification can take up to 5 minutes
-- Check https://knowthat.ai/agents/YOUR-AGENT-SLUG
+### Custom Logger
 
-### Lost your identity file?
-
-- Unfortunately, DIDs cannot be recovered
-- You'll need to create a new identity
-- Previous registrations cannot be updated
+```typescript
+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
 
@@ -265,56 +207,90 @@ Main function to enable identity for your MCP server.
 
 **Options:**
 
-- `name` (string): Your agent's display name
-- `description` (string): What your agent does
-- `repository` (string): GitHub repo URL
-- `didHost` (string): Custom DID host (default: "knowthat.ai")
-
-**Returns:** `Promise<MCPIdentity>`
+```typescript
+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` class
+### `MCPIdentity` Methods
 
-**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
 
-- `sign(message)`: Sign a message with your private key
-- `verify(message, signature)`: Verify a signature
-- `respondToChallenge(challenge)`: Handle MCP-I authentication
-- `signResponse(response)`: Add identity to any response
-- `requestEditAccess()`: Get edit URL for your agent profile
-- `getRegistryStatus()`: Check registration status
+## Files Created
 
-## FAQ
+```
+.mcp-identity.json    # Your agent's identity (encrypted if password set)
+```
 
-**Q: Is this package affiliated with Anthropic?**  
-A: No, this is a community package implementing the MCP-I specification.
+## Security Best Practices
 
-**Q: Can I use this without MCP?**  
-A: Yes! The `MCPIdentity` class can be used standalone for any identity needs.
+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
 
-**Q: What happens if KnowThat.ai is down?**  
-A: After initial registration, your agent works offline. The DID is self-contained.
+## Performance Tips
 
-**Q: Can I change my agent's name later?**  
-A: Yes, use `requestEditAccess()` to get an edit URL with cryptographic proof.
+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
 
-**Q: Why only KnowThat.ai registry right now?**  
-A: We're building the ecosystem! As directories adopt MCP-I, your agent will automatically be discoverable across all of them.
+## Troubleshooting
 
-**Q: I run a directory. How can I support MCP-I?**  
-A: [Contact us](https://github.com/kya-os/mcp-i/issues) to discuss integration. We're actively seeking directory partners.
+### Lambda/Edge Issues
 
-**Q: Is this production-ready?**  
-A: Yes, but currently in beta. The API may change before 1.0.
+- Ensure `storage: 'memory'` or `'auto'`
+- Use `transport: 'fetch'` for edge runtimes
+- Set `logLevel: 'silent'` to avoid console issues
 
-## Join the Identity Revolution
+### Key Rotation Failures
 
-**MCP Server Developers:** Give your server an identity today. Be discoverable, build reputation, and future-proof your agent for the emerging ecosystem.
+- Check network connectivity to knowthat.ai
+- Verify current keys are not corrupted
+- Manual rotation: `await identity.rotateKeys('recovery')`
 
-```bash
-npm install @kya-os/mcp-i
-```
+### Performance Issues
 
-**Directory Maintainers:** Want to be part of the decentralized identity ecosystem? MCP-I enables you to list only verified agents with cryptographic proof of identity. [Let's talk integration →](https://github.com/orgs/modelcontextprotocol-identity/discussions/new?category=mcp-i-directories)
+- Verify signature caching is working
+- Check lazy loading (should see delayed first signature)
+- Use memory storage when possible
 
 ## License
 

package/dist/auto.d.ts

@@ -1,13 +1 @@
-/**
- * Auto-initialization for MCP Identity
- *
- * Just import this file to automatically enable MCP-I for any MCP server:
- *
- * ```typescript
- * import "@kya-os/mcp-i/auto";
- * ```
- *
- * That's it! Your MCP server now has identity.
- */
 export {};
-//# sourceMappingURL=auto.d.ts.map

package/dist/auto.js

@@ -1,24 +1,13 @@
 "use strict";
-/**
- * Auto-initialization for MCP Identity
- *
- * Just import this file to automatically enable MCP-I for any MCP server:
- *
- * ```typescript
- * import "@kya-os/mcp-i/auto";
- * ```
- *
- * That's it! Your MCP server now has identity.
- */
 Object.defineProperty(exports, "__esModule", { value: true });
 const index_1 = require("./index");
-// Auto-initialize on import
+const logger_1 = require("./logger");
 (async () => {
     try {
         await (0, index_1.enableMCPIdentity)();
     }
     catch (error) {
-        console.error('[MCP-I] Failed to auto-initialize:', error);
+        const logger = (0, logger_1.getLogger)();
+        logger.error('[MCP-I] Failed to auto-initialize:', error);
     }
 })();
-//# sourceMappingURL=auto.js.map

package/dist/crypto.d.ts

@@ -1,32 +1,16 @@
-/**
- * Cryptographic utilities for MCP-I
- * Implements Ed25519 signing and verification for challenge-response authentication
- */
-/**
- * Generate a new Ed25519 key pair
- */
-export declare function generateKeyPair(): Promise<{
+export interface PrecomputedKeyPair {
     publicKey: string;
     privateKey: string;
-}>;
-/**
- * Sign a message with Ed25519
- */
+    publicKeyBytes?: Uint8Array;
+    privateKeyBytes?: Uint8Array;
+}
+export declare function generateKeyPair(): Promise<PrecomputedKeyPair>;
 export declare function sign(message: string | Buffer, privateKeyBase64: string): Promise<string>;
-/**
- * Verify an Ed25519 signature
- */
 export declare function verify(message: string | Buffer, signatureBase64: string, publicKeyBase64: string): Promise<boolean>;
-/**
- * Generate a cryptographically secure nonce
- */
-export declare function generateNonce(length?: number): string;
-/**
- * Constant-time string comparison to prevent timing attacks
- */
+export declare function generateNonce(length?: number): Promise<string>;
+export declare function generateNonceSync(length?: number): string;
 export declare function constantTimeEqual(a: string, b: string): boolean;
-/**
- * Convert Ed25519 public key to did:key format
- */
 export declare function publicKeyToDid(publicKeyBase64: string): string;
-//# sourceMappingURL=crypto.d.ts.map
+export declare function encrypt(data: string, password: string): Promise<string>;
+export declare function decrypt(encryptedData: string, password: string): Promise<string>;
+export declare function clearCache(): void;