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

package/README.md

@@ -1,10 +1,45 @@
 # @kya-os/mcp-i
 
-Ultra-light MCP Identity auto-registration. Give any MCP server a verifiable identity with just 2 lines of code.
+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.
+
+[![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)
+[![MCP-I Conformance](https://img.shields.io/badge/MCP--I-Level%202-green)](https://modelcontextprotocol-identity.io)
+
+## Why Your MCP Server Needs This
+
+**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
+
+**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
 
 ## The Vision
 
-Make MCP-I adoption a no-brainer for the hundreds of thousands of MCP servers. Zero friction, immediate benefits.
+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)
 
 ## Installation
 
@@ -12,86 +47,275 @@ Make MCP-I adoption a no-brainer for the hundreds of thousands of MCP servers. Z
 npm install @kya-os/mcp-i
 ```
 
-## Usage
+## Quick Start
 
-### Option 1: Zero Configuration (Recommended)
+### 1. Zero Configuration (Recommended)
 
 ```typescript
-import "@kya-os/mcp-i/auto";  // That's it! Your server now has identity
+import "@kya-os/mcp-i/auto";
+// That's it! Your server now has cryptographic identity
 ```
 
-### Option 2: With Configuration
+### 2. With Configuration
 
 ```typescript
 import { enableMCPIdentity } from "@kya-os/mcp-i";
 
 await enableMCPIdentity({
-  name: "Calendar Booker",
-  description: "Professional calendar booking for AI agents",
-  repository: "https://github.com/awesome-dev/calendar-booker"
+  name: "Calendar Assistant",
+  description: "AI agent for professional calendar management",
+  repository: "https://github.com/your-org/calendar-assistant",
 });
 ```
 
-## What Happens
+## Current State & Roadmap
+
+**Today:**
 
-1. **First Run**: Automatically registers with knowthat.ai and gets a DID
-2. **Identity Saved**: Persists to `.env.local` and `.mcp-identity.json`
-3. **All Responses Signed**: Every response includes `_mcp_identity` field
-4. **MCP-I Handshake**: Automatically handles challenge-response authentication
-5. **Capabilities Advertised**: Server advertises MCP-I support to clients
+- ✅ Your MCP server gets a DID (decentralized identifier)
+- ✅ Every response is cryptographically signed
+- ✅ Registered on KnowThat.ai registry
+- ✅ Full MCP-I Level 2 conformance
+
+**Coming Soon:**
+
+- 🔜 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:
+
+1. **First Run Only**:
+
+   - Generates Ed25519 cryptographic keypair
+   - Registers with KnowThat.ai to obtain a DID
+   - Saves identity to `.mcp-identity.json`
+   - Total time: ~2 seconds
+
+2. **Every Subsequent Run**:
+
+   - Loads existing identity from disk
+   - Zero API calls, instant startup
+   - Maintains the same DID forever
+
+3. **During Operation**:
+   - Every response includes `_mcp_identity` field with cryptographic signature
+   - Handles MCP-I challenge-response authentication automatically
+   - Advertises identity capabilities to clients
 
 ## Example Response
 
+After enabling MCP-I, all your server responses automatically include cryptographic signatures:
+
 ```json
 {
-  "content": [{
-    "type": "text",
-    "text": "Event booked successfully!"
-  }],
+  "content": [
+    {
+      "type": "text",
+      "text": "Meeting scheduled for tomorrow at 2 PM"
+    }
+  ],
   "_mcp_identity": {
-    "did": "did:web:knowthat.ai:agents:calendar-booker",
+    "did": "did:web:knowthat.ai:agents:calendar-assistant",
     "signature": "0x3045...",
-    "timestamp": "2025-01-31T10:00:00Z",
+    "timestamp": "2025-01-06T10:00:00Z",
     "conformanceLevel": 2
   }
 }
 ```
 
-## Benefits
+## Advanced Configuration
 
-- ✅ **Verification Badge** on Smithery and other directories
-- 🔝 **Priority Discovery** in search results
-- 🔐 **Access to Identity-Aware APIs** with higher rate limits
-- 📊 **Analytics & Reputation** tracking
-- 🛡️ **Protection Against Impersonation**
+### Registry Support (Future-Ready)
 
-## How It Works
+As more directories adopt MCP-I, your agent will automatically be discoverable across the ecosystem:
 
-The package automatically:
-1. Patches the MCP Server class to inject identity into all responses
-2. Handles MCP-I challenge-response authentication
-3. Advertises capabilities in server info
-4. Works with all transports (STDIO, SSE, HTTP)
+```typescript
+await enableMCPIdentity({
+  name: "My Agent",
+  registries: "verified", // default
+  // Currently registers with KnowThat.ai
+  // Additional registries will be supported as they adopt MCP-I
+});
+```
 
-## Environment Variables
+**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.
 
-After first run, these are saved automatically:
+### Custom DID Host
+
+For enterprises who want to host their own DID:
+
+```typescript
+await enableMCPIdentity({
+  name: "Enterprise Agent",
+  didHost: "company.com", // Creates did:web:company.com:agents:...
+});
+```
+
+Note: The Agent's did must discoverable via company.com/.well-known/did.json
+
+### Edit Your Agent Profile
+
+Only you can edit your agent's profile, thanks to cryptographic proof:
+
+```typescript
+const identity = await enableMCPIdentity();
+
+// 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=...
+```
+
+## 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
+
+**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
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant Client as AI Client
+    participant Agent as Your MCP Server
+    participant API as Protected API
+
+    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!"
+```
+
+## Files Created
+
+After initialization, you'll see these files in your project root:
 
-```bash
-AGENT_DID="did:web:knowthat.ai:agents:your-agent"
-AGENT_PUBLIC_KEY="base64-encoded-public-key"
-AGENT_PRIVATE_KEY="base64-encoded-private-key"
-AGENT_ID="uuid"
-AGENT_SLUG="your-agent-slug"
 ```
+.mcp-identity.json    # Your agent's identity (⚠️ Contains private key!)
+```
+
+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"
+  }
+}
+```
+
+## 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
+
+### Lost your identity file?
+
+- Unfortunately, DIDs cannot be recovered
+- You'll need to create a new identity
+- Previous registrations cannot be updated
 
-## Security
+## API Reference
+
+### `enableMCPIdentity(options?)`
+
+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>`
+
+### `MCPIdentity` class
+
+**Methods:**
+
+- `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
+
+## FAQ
+
+**Q: Is this package affiliated with Anthropic?**  
+A: No, this is a community package implementing the MCP-I specification.
+
+**Q: Can I use this without MCP?**  
+A: Yes! The `MCPIdentity` class can be used standalone for any identity needs.
+
+**Q: What happens if KnowThat.ai is down?**  
+A: After initial registration, your agent works offline. The DID is self-contained.
+
+**Q: Can I change my agent's name later?**  
+A: Yes, use `requestEditAccess()` to get an edit URL with cryptographic proof.
+
+**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.
+
+**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.
+
+**Q: Is this production-ready?**  
+A: Yes, but currently in beta. The API may change before 1.0.
+
+## Join the Identity Revolution
+
+**MCP Server Developers:** Give your server an identity today. Be discoverable, build reputation, and future-proof your agent for the emerging ecosystem.
+
+```bash
+npm install @kya-os/mcp-i
+```
 
-- Private keys are stored locally, never sent to knowthat.ai
-- All responses are cryptographically signed with Ed25519
-- Challenge-response prevents replay attacks
-- Nonce tracking prevents reuse
+**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)
 
 ## License
 
-MIT
+MIT

package/dist/index.d.ts

@@ -12,9 +12,18 @@
  * import { enableMCPIdentity } from "@kya-os/mcp-i";
  * await enableMCPIdentity({ name: "My Amazing Agent" });
  * ```
+ *
+ * Future multi-registry support:
+ * ```typescript
+ * await enableMCPIdentity({
+ *   name: "My Agent",
+ *   // Additional registries will be supported as directories adopt MCP-I
+ * });
+ * ```
  */
-import { MCPIdentityOptions, Challenge, ChallengeResponse, MCPICapabilities, SignedResponse } from './types';
+import { MCPIdentityOptions, Challenge, ChallengeResponse, MCPICapabilities, SignedResponse, RegistryStatus, RegistryName } from './types';
 export * from './types';
+export { RegistryFactory, REGISTRY_TIERS, resolveRegistries } from './registry';
 export declare class MCPIdentity {
     readonly did: string;
     readonly publicKey: string;
@@ -23,11 +32,43 @@ export declare class MCPIdentity {
     private enableNonceTracking;
     private usedNonces;
     private nonceCleanupInterval?;
+    readonly didHost: string;
+    private registries;
+    private registryAdapters;
     private constructor();
     /**
      * Initialize MCP Identity - the main entry point
+     *
+     * IMPORTANT: This only makes API calls in these cases:
+     * 1. First time ever (no identity exists) - registers with all specified registries
+     * 2. Adding new registries to existing identity - only calls the new registries
+     *
+     * After initial registration, all subsequent calls load from disk with NO API calls.
      */
     static init(options?: MCPIdentityOptions): Promise<MCPIdentity>;
+    /**
+     * Sync identity to additional registries
+     *
+     * RATE LIMITED: Each registry can only be synced once per minute to prevent spam.
+     * Skips registries that are already active.
+     */
+    syncToRegistries(registryNames: RegistryName[]): Promise<void>;
+    /**
+     * Add a new registry
+     */
+    addRegistry(registryName: RegistryName): Promise<void>;
+    /**
+     * Add multiple registries
+     */
+    addRegistries(registryNames: RegistryName[]): Promise<void>;
+    /**
+     * Get current registry status
+     */
+    getRegistryStatus(): RegistryStatus[];
+    /**
+     * Check if registered with a specific registry
+     */
+    isRegisteredWith(registryName: RegistryName): boolean;
     /**
      * Sign a message with the agent's private key using Ed25519
      */
@@ -52,6 +93,11 @@ export declare class MCPIdentity {
      * Generate a new nonce for challenges
      */
     static generateNonce(): string;
+    /**
+     * Request edit access to agent profile
+     * Returns a signed URL for editing the agent on the registry
+     */
+    requestEditAccess(registryName?: string): Promise<string>;
     /**
      * Clean up old nonces periodically to prevent memory leaks
      */
@@ -60,6 +106,22 @@ export declare class MCPIdentity {
      * Clean up resources
      */
     destroy(): void;
+    /**
+     * Helper to extract agent name from DID
+     */
+    private extractAgentName;
+    /**
+     * Helper to extract agent ID
+     */
+    private extractAgentId;
+    /**
+     * Helper to extract agent slug
+     */
+    private extractAgentSlug;
+    /**
+     * Persist updated registry status
+     */
+    private persistRegistryStatus;
 }
 /**
  * Enable MCP Identity for any MCP server

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAMH,OAAO,EACL,kBAAkB,EAGlB,SAAS,EACT,iBAAiB,EACjB,gBAAgB,EAChB,cAAc,EACf,MAAM,SAAS,CAAC;AAGjB,cAAc,SAAS,CAAC;AAKxB,qBAAa,WAAW;IACtB,SAAgB,GAAG,EAAE,MAAM,CAAC;IAC5B,SAAgB,SAAS,EAAE,MAAM,CAAC;IAClC,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,kBAAkB,CAAS;IACnC,OAAO,CAAC,mBAAmB,CAAU;IACrC,OAAO,CAAC,UAAU,CAA0B;IAC5C,OAAO,CAAC,oBAAoB,CAAC,CAAiB;IAE9C,OAAO;IAgBP;;OAEG;WACU,IAAI,CAAC,OAAO,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,WAAW,CAAC;IAkDrE;;OAEG;IACG,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAIrD;;OAEG;IACG,MAAM,CACV,OAAO,EAAE,MAAM,GAAG,MAAM,EACxB,SAAS,EAAE,MAAM,EACjB,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,OAAO,CAAC;IAQnB;;OAEG;IACG,kBAAkB,CAAC,SAAS,EAAE,SAAS,GAAG,OAAO,CAAC,iBAAiB,CAAC;IA4C1E;;OAEG;IACH,eAAe,IAAI,gBAAgB;IAYnC;;OAEG;IACG,YAAY,CAAC,CAAC,GAAG,GAAG,EAAE,QAAQ,EAAE,CAAC,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC;IA2BpE;;OAEG;IACH,MAAM,CAAC,aAAa,IAAI,MAAM;IAI9B;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAWzB;;OAEG;IACH,OAAO;CAMR;AAED;;;GAGG;AACH,wBAAsB,iBAAiB,CAAC,OAAO,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,WAAW,CAAC,CAW1F"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAMH,OAAO,EACL,kBAAkB,EAGlB,SAAS,EACT,iBAAiB,EACjB,gBAAgB,EAChB,cAAc,EACd,cAAc,EAGd,YAAY,EACb,MAAM,SAAS,CAAC;AAIjB,cAAc,SAAS,CAAC;AACxB,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAKhF,qBAAa,WAAW;IACtB,SAAgB,GAAG,EAAE,MAAM,CAAC;IAC5B,SAAgB,SAAS,EAAE,MAAM,CAAC;IAClC,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,kBAAkB,CAAS;IACnC,OAAO,CAAC,mBAAmB,CAAU;IACrC,OAAO,CAAC,UAAU,CAA0B;IAC5C,OAAO,CAAC,oBAAoB,CAAC,CAAiB;IAG9C,SAAgB,OAAO,EAAE,MAAM,CAAC;IAChC,OAAO,CAAC,UAAU,CAAmB;IACrC,OAAO,CAAC,gBAAgB,CAA2C;IAEnE,OAAO;IA2BP;;;;;;;;OAQG;WACU,IAAI,CAAC,OAAO,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,WAAW,CAAC;IAqHrE;;;;;OAKG;IACG,gBAAgB,CAAC,aAAa,EAAE,YAAY,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IA2EpE;;OAEG;IACG,WAAW,CAAC,YAAY,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAI5D;;OAEG;IACG,aAAa,CAAC,aAAa,EAAE,YAAY,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAIjE;;OAEG;IACH,iBAAiB,IAAI,cAAc,EAAE;IAIrC;;OAEG;IACH,gBAAgB,CAAC,YAAY,EAAE,YAAY,GAAG,OAAO;IAIrD;;OAEG;IACG,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAIrD;;OAEG;IACG,MAAM,CACV,OAAO,EAAE,MAAM,GAAG,MAAM,EACxB,SAAS,EAAE,MAAM,EACjB,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,OAAO,CAAC;IAQnB;;OAEG;IACG,kBAAkB,CAAC,SAAS,EAAE,SAAS,GAAG,OAAO,CAAC,iBAAiB,CAAC;IA4C1E;;OAEG;IACH,eAAe,IAAI,gBAAgB;IAqBnC;;OAEG;IACG,YAAY,CAAC,CAAC,GAAG,GAAG,EAAE,QAAQ,EAAE,CAAC,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC;IA2BpE;;OAEG;IACH,MAAM,CAAC,aAAa,IAAI,MAAM;IAI9B;;;OAGG;IACG,iBAAiB,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAmB/D;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAWzB;;OAEG;IACH,OAAO;IAOP;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAKxB;;OAEG;IACH,OAAO,CAAC,cAAc;IAItB;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAKxB;;OAEG;YACW,qBAAqB;CAWpC;AAED;;;GAGG;AACH,wBAAsB,iBAAiB,CAAC,OAAO,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,WAAW,CAAC,CAW1F"}