@kya-os/mcp-i 1.7.12 → 1.9.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (58) hide show
  1. package/README.md +218 -333
  2. package/dist/114.js +1 -0
  3. package/dist/139.js +1 -0
  4. package/dist/200.js +1 -0
  5. package/dist/202.js +1 -0
  6. package/dist/238.js +1 -0
  7. package/dist/263.js +1 -0
  8. package/dist/294.js +1 -0
  9. package/dist/295.js +1 -1
  10. package/dist/374.js +1 -0
  11. package/dist/529.js +1 -0
  12. package/dist/627.js +1 -0
  13. package/dist/644.js +1 -0
  14. package/dist/669.js +1 -0
  15. package/dist/857.js +1 -0
  16. package/dist/866.js +1 -1
  17. package/dist/{941.js → 966.js} +1 -1
  18. package/dist/997.js +1 -0
  19. package/dist/providers/node-providers.d.ts +1 -1
  20. package/dist/providers/node-providers.js +2 -2
  21. package/dist/runtime/adapter-express.js +5 -5
  22. package/dist/runtime/adapter-express.js.LICENSE.txt +0 -7
  23. package/dist/runtime/adapter-nextjs.js +6 -6
  24. package/dist/runtime/adapter-nextjs.js.LICENSE.txt +0 -189
  25. package/dist/runtime/auth-handshake.d.ts +4 -159
  26. package/dist/runtime/auth-handshake.js +8 -249
  27. package/dist/runtime/http.js +5 -5
  28. package/dist/runtime/http.js.LICENSE.txt +0 -7
  29. package/dist/runtime/mcpi-runtime.d.ts +4 -0
  30. package/dist/runtime/mcpi-runtime.js +58 -43
  31. package/dist/runtime/outbound-delegation.d.ts +34 -0
  32. package/dist/runtime/outbound-delegation.js +134 -0
  33. package/dist/runtime/proof.d.ts +13 -88
  34. package/dist/runtime/proof.js +11 -225
  35. package/dist/runtime/request-context.d.ts +41 -0
  36. package/dist/runtime/request-context.js +48 -0
  37. package/dist/runtime/session.d.ts +13 -104
  38. package/dist/runtime/session.js +31 -267
  39. package/dist/runtime/stdio.js +6 -7
  40. package/dist/runtime/utils/server.d.ts +2 -8
  41. package/dist/runtime/utils/tools.js +17 -3
  42. package/dist/storage/delegation.js +2 -2
  43. package/package.json +32 -31
  44. package/dist/207.js +0 -1
  45. package/dist/25.js +0 -1
  46. package/dist/387.js +0 -1
  47. package/dist/406.js +0 -1
  48. package/dist/448.js +0 -1
  49. package/dist/478.js +0 -1
  50. package/dist/482.js +0 -1
  51. package/dist/575.js +0 -1
  52. package/dist/67.js +0 -1
  53. package/dist/743.js +0 -1
  54. package/dist/784.js +0 -1
  55. package/dist/844.js +0 -1
  56. package/dist/936.js +0 -1
  57. package/dist/988.js +0 -1
  58. package/dist/runtime/stdio.js.LICENSE.txt +0 -234
package/README.md CHANGED
@@ -5,448 +5,333 @@
5
5
  <img alt="MCP-I logo" src="https://raw.githubusercontent.com/modelcontextprotocol-identity/xmcp-i/main/assets/mcp-i-logo-light.png" height="128">
6
6
  </picture>
7
7
  </a>
8
- <h1>xmcp-i</h1>
8
+ <h1>@kya-os/mcp-i</h1>
9
9
 
10
- <a href="https://github.com/modelcontextprotocol-identity/xmcp-i"><img alt="XMCP-I" src="https://img.shields.io/badge/XMCP--I-000000.svg?style=for-the-badge&labelColor=000"></a>
11
- <a href="https://www.npmjs.com/package/xmcp-i"><img alt="NPM version" src="https://img.shields.io/npm/v/xmcp-i.svg?style=for-the-badge&labelColor=000000"></a>
12
- <a href="https://github.com/modelcontextprotocol-identity/xmcp-i/blob/main/license.md"><img alt="License" src="https://img.shields.io/npm/l/xmcp-i.svg?style=for-the-badge&labelColor=000000"></a>
10
+ <a href="https://github.com/modelcontextprotocol-identity/xmcp-i"><img alt="MCP-I" src="https://img.shields.io/badge/MCP--I-000000.svg?style=for-the-badge&labelColor=000"></a>
11
+ <a href="https://www.npmjs.com/package/@kya-os/mcp-i"><img alt="NPM version" src="https://img.shields.io/npm/v/@kya-os/mcp-i.svg?style=for-the-badge&labelColor=000000"></a>
12
+ <a href="https://github.com/modelcontextprotocol-identity/xmcp-i/blob/main/license.md"><img alt="License" src="https://img.shields.io/npm/l/@kya-os/mcp-i.svg?style=for-the-badge&labelColor=000000"></a>
13
13
 
14
14
  </div>
15
15
 
16
- ## Own Your AI Agent with Cryptographic Identity
16
+ ## Node.js Runtime for MCP-I
17
17
 
18
- `xmcp-i` enables you to **create your own AI agents** with cryptographic identity and secure delegation. Register and claim your agents with [knowthat.ai](https://knowthat.ai), store your identity securely within them, and delegate or revoke permissions as needed. Built on the XMCP framework with identity features baked in from day one.
18
+ `@kya-os/mcp-i` is the Node.js implementation of the MCP-I (Model Context Protocol with Identity) framework. It provides identity management, cryptographic proof generation, session handling, and delegation verification for building secure AI agents.
19
19
 
20
20
  ## Quick Start
21
21
 
22
- Create your first owned AI agent:
23
-
24
- ```bash
25
- npx @kya-os/create-xmcpi-app@latest my-agent
26
- ```
27
-
28
- Then register and claim ownership at [knowthat.ai](https://knowthat.ai)
29
-
30
- > **New to XMCP-I?** Use [`@kya-os/create-xmcpi-app`](https://www.npmjs.com/package/@kya-os/create-xmcpi-app) to scaffold a complete agent with identity. For existing projects, install `@kya-os/xmcpi` directly.
31
-
32
- ## Installation
33
-
34
22
  ### For New Projects
35
23
 
24
+ Use the scaffolding tool to create a new MCP-I project:
25
+
36
26
  ```bash
37
- npx create-xmcpi-app@latest my-agent
27
+ npx @kya-os/create-mcpi-app my-agent
28
+ cd my-agent
29
+ npm run dev
38
30
  ```
39
31
 
40
32
  ### For Existing Projects
41
33
 
42
34
  ```bash
43
- npx init-xmcp-i@latest
35
+ npm install @kya-os/mcp-i
44
36
  ```
45
37
 
46
- This will add identity features to your existing Node.js/TypeScript project with automatic framework detection and configuration.
47
-
48
- ## Why Agent Ownership Matters
49
-
50
- ⊹ **True Ownership** - Your agent belongs to you, not a platform\
51
- ⊹ **Cryptographic Security** - Ed25519 keys and DID-based identity\
52
- ⊹ **Permission Control** - Delegate and revoke capabilities securely\
53
- ⊹ **Verifiable Actions** - All responses are cryptographically signed\
54
- ⊹ **Decentralized Trust** - No central authority controls your agent\
55
- ⊹ **Portable Identity** - Move your agent between platforms while keeping ownership
38
+ ## Core Features
56
39
 
57
- ### Cryptographic Foundation
40
+ - **Identity Management** - Ed25519 key generation and DID-based identity
41
+ - **Cryptographic Proofs** - JWS proof generation for tool responses
42
+ - **Session Management** - Nonce-protected sessions with configurable TTL
43
+ - **Delegation Verification** - Verify delegated permissions from AgentShield
44
+ - **Tool Protection** - Configure which tools require delegation
45
+ - **Audit Logging** - Track all identity operations
46
+ - **Well-Known Endpoints** - Standard MCP-I discovery endpoints
58
47
 
59
- - **DID Generation**: Decentralized identifiers from public keys
60
- - **Automatic Signing**: All responses signed with your private key
61
- - **Key Security**: Private keys never leave your control
48
+ ## API Reference
62
49
 
63
- ## Security and Trust
50
+ ### CLI Identity Setup
64
51
 
65
- **Agent Ownership Verification**: Every XMCP-I agent generates a cryptographic proof of ownership that can be verified independently. When you register your agent with knowthat.ai, you establish a permanent, tamper-proof claim to your agent's identity.
52
+ Initialize identity for CLI tools and development:
66
53
 
67
- **Decentralized Trust**: Your agent's identity doesn't depend on any central authority. The cryptographic keys are generated locally and never shared. Even if knowthat.ai goes offline, your agent retains its identity and ownership proof.
68
-
69
- **Secure Delegation**: Permission delegation uses time-bound, cryptographically signed tokens. You can grant specific capabilities to other users or systems, with full audit trails and instant revocation capabilities.
70
-
71
- ## Real-World Benefits for Developers & Businesses
72
-
73
- ### Privacy-First Tracking & Analytics
74
-
75
- Unlike traditional web tracking (cookies, pixels), XMCP-I provides **ethical data collection**:
76
-
77
- - Users can see exactly what data is stored about them
78
- - Users can revoke access instantly at any time
79
- - Businesses get analytics for retargeting without violating privacy
80
- - Think "GDPR-compliant by design" - users control their data completely
81
-
82
- ### XMCP-I Allows AI in Regulated Industries
83
-
84
- Industries like healthcare, law, and finance can now use AI while maintaining compliance:
85
-
86
- **The Problem**: These industries need AI efficiency but can't use most AI services due to:
54
+ ```typescript
55
+ import { enableMCPIdentityCLI } from "@kya-os/mcp-i";
87
56
 
88
- - Data privacy regulations (HIPAA, GDPR, SOX)
89
- - Audit requirements (who did what, when?)
90
- - Client confidentiality obligations
57
+ const result = await enableMCPIdentityCLI({
58
+ name: "my-agent",
59
+ description: "My AI agent with identity",
60
+ onProgress: (event) => {
61
+ console.log(`${event.stage}: ${event.message}`);
62
+ },
63
+ });
91
64
 
92
- **The Solution**: XMCP-I provides:
65
+ console.log(`Agent DID: ${result.identity.did}`);
66
+ console.log(`Claim URL: ${result.metadata.claimUrl}`);
67
+ ```
93
68
 
94
- - **Provable Privacy**: Cryptographic proof of data handling
95
- - **Complete Audit Trails**: Every AI action is signed and traceable
96
- - **User Control**: Clients can revoke AI access to their data instantly
97
- - **Regulatory Compliance**: Built-in features for GDPR, HIPAA, etc.
98
- - **EU AI Act Compliance**: Built-in audit trails and user consent mechanisms
69
+ **Options:**
99
70
 
100
- **Real Example**: A law firm can now use AI for document review because:
71
+ | Option | Type | Description |
72
+ |--------|------|-------------|
73
+ | `name` | `string` | Agent name for registration |
74
+ | `description` | `string` | Agent description |
75
+ | `repository` | `string` | Git repository URL |
76
+ | `endpoint` | `string` | KTA endpoint (default: `https://knowthat.ai`) |
77
+ | `logLevel` | `'silent' \| 'info' \| 'debug'` | Logging verbosity |
78
+ | `onProgress` | `(event) => void` | Progress callback |
79
+ | `skipRegistration` | `boolean` | Skip KTA registration |
101
80
 
102
- - Clients control exactly which documents the AI can access
103
- - All AI actions are cryptographically logged
104
- - Clients can revoke access immediately if they switch firms
105
- - The firm can prove to regulators exactly how data was handled
81
+ ### Identity Manager
106
82
 
107
- ## Installation
83
+ Direct identity management for runtime use:
108
84
 
109
- ### For New Projects
85
+ ```typescript
86
+ import { IdentityManager, type AgentIdentity } from "@kya-os/mcp-i";
110
87
 
111
- ```bash
112
- npx @kya-os/create-xmcpi-app@latest my-agent
113
- ```
88
+ const manager = new IdentityManager({
89
+ environment: "development",
90
+ devIdentityPath: ".mcpi/identity.json",
91
+ });
114
92
 
115
- ### For Existing Projects
93
+ // Load or generate identity
94
+ const identity: AgentIdentity = await manager.ensureIdentity();
116
95
 
117
- ```bash
118
- npm install @kya-os/xmcpi
119
- # or
120
- yarn add @kya-os/xmcpi
121
- # or
122
- pnpm add @kya-os/xmcpi
96
+ console.log(identity.did); // did:key:z6Mk...
97
+ console.log(identity.publicKey); // Base64-encoded Ed25519 public key
123
98
  ```
124
99
 
125
- ## Migrating from XMCP
100
+ ### MCP-I Runtime
126
101
 
127
- Your existing XMCP agents can gain ownership capabilities:
102
+ Create a full MCP-I runtime with all providers:
128
103
 
129
104
  ```typescript
130
- // Before (original XMCP - platform owned)
131
- import { createXMCPServer } from "xmcp";
105
+ import { createMCPIRuntime } from "@kya-os/mcp-i";
132
106
 
133
- // After (XMCP-I - you own the agent!)
134
- import { createXMCPServer } from "xmcp-i";
135
- ```
136
-
137
- Your existing code works unchanged, but now your agent:
138
-
139
- - ✅ Has its own cryptographic identity
140
- - ✅ Can be registered and claimed by you at knowthat.ai
141
- - ✅ Signs all responses automatically
142
- - ✅ Supports secure permission delegation
143
- - ✅ Provides verifiable ownership proof
144
-
145
- ## Core Identity Features
146
-
147
- ### Agent Identity Verification
107
+ const runtime = await createMCPIRuntime({
108
+ environment: "production",
109
+ session: {
110
+ timestampSkewSeconds: 120,
111
+ ttlMinutes: 30,
112
+ },
113
+ audit: {
114
+ enabled: true,
115
+ },
116
+ });
148
117
 
149
- Your agent provides cryptographic proof of ownership:
118
+ // Handle MCP handshake
119
+ const handshakeResult = await runtime.handleHandshake(request);
150
120
 
151
- ```bash
152
- # Your agent's identity includes:
153
- {
154
- "did": "did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK",
155
- "publicKey": "-----BEGIN PUBLIC KEY-----\n...",
156
- "privateKey": "-----BEGIN PRIVATE KEY-----\n...", // Never shared
157
- "agentId": "agent-abc123...",
158
- "capabilities": {
159
- "tools": true,
160
- "signing": true,
161
- "verification": true,
162
- "delegation": true
163
- }
164
- }
121
+ // Process tool calls with proof generation
122
+ const result = await runtime.processToolCall(
123
+ toolName,
124
+ args,
125
+ handler,
126
+ sessionContext
127
+ );
165
128
  ```
166
129
 
167
- - **Public Key**: Can be shared and verified by anyone
168
- - **Private Key**: Never leaves your control, stored securely locally
169
- - **DID**: Globally unique identifier generated from your public key
170
- - **Signatures**: All agent responses include cryptographic signatures
130
+ ### Delegation Verification
171
131
 
172
- ### Trust Infrastructure
173
-
174
- - `GET /.well-known/mcp-identity/health` - Health check with identity
175
- - `GET /.well-known/mcp-identity/self` - Agent identity information
176
- - `POST /.well-known/mcp-identity/verify` - Verify signatures
177
- - `GET /.well-known/mcp-identity/resolve/:did` - Resolve DIDs
178
-
179
- ### Built-in Identity Tools & Self-Sovereign Features
180
-
181
- - `get-identity-info` - Comprehensive agent identity details
182
- - `sign-message` - Sign messages with your private key
183
- - `verify-signature` - Verify signatures against DIDs
184
- - `get-server-status` - Agent status with identity information
185
- - `get-user-data` - Allow users to see all stored data about them
186
- - `revoke-user-access` - Let users instantly revoke AI access to their data
187
- - `export-user-data` - Enable users to export their data for portability
188
-
189
- ## Secure Permission Delegation
190
-
191
- Control what your agent can do and for whom:
132
+ Verify delegated permissions:
192
133
 
193
134
  ```typescript
194
- // Delegate specific permissions to other DIDs
195
- await agent.delegate({
196
- to: "did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK",
197
- permissions: ["read:data", "execute:safe-actions"],
198
- expires: new Date("2025-12-31"),
199
- conditions: {
200
- rate_limit: "100/hour",
201
- allowed_tools: ["get-weather", "search-docs"],
202
- },
135
+ import { createDelegationVerifier } from "@kya-os/mcp-i";
136
+
137
+ const verifier = createDelegationVerifier({
138
+ agentShieldApiUrl: "https://kya.vouched.id",
139
+ agentShieldApiKey: process.env.AGENTSHIELD_API_KEY,
203
140
  });
204
141
 
205
- // Revoke permissions instantly
206
- await agent.revoke({
207
- delegation_id: "del_abc123",
208
- reason: "Project completed",
142
+ const result = await verifier.verify({
143
+ delegationToken: token,
144
+ requiredScopes: ["checkout:execute"],
145
+ agentDid: runtime.getIdentity().did,
209
146
  });
210
147
 
211
- // All delegation changes are cryptographically signed and verifiable
148
+ if (result.valid) {
149
+ console.log("Delegation verified:", result.delegationId);
150
+ }
212
151
  ```
213
152
 
214
- ### Secure Delegation Example
153
+ ### Tool Protection
215
154
 
216
- Grant specific permissions to other users while maintaining ownership:
155
+ Configure which tools require delegation:
217
156
 
218
157
  ```typescript
219
- // Example: Grant read-only access to specific tools
220
- await agent.delegate({
221
- to: "user@example.com",
222
- permissions: ["read:weather", "read:docs"],
223
- expires: "2025-12-31T23:59:59Z",
224
- conditions: { rate_limit: "100/hour" },
158
+ import {
159
+ ToolProtectionResolver,
160
+ AgentShieldToolProtectionSource
161
+ } from "@kya-os/mcp-i";
162
+
163
+ // Load protection config from AgentShield
164
+ const source = new AgentShieldToolProtectionSource({
165
+ apiUrl: "https://kya.vouched.id",
166
+ apiKey: process.env.AGENTSHIELD_API_KEY,
167
+ projectId: process.env.AGENTSHIELD_PROJECT_ID,
225
168
  });
226
- ```
227
-
228
- ## Platform Support with Identity Persistence
229
169
 
230
- Deploy your owned agents anywhere with secure identity storage:
170
+ const resolver = new ToolProtectionResolver([source]);
171
+ const protection = await resolver.getProtection("checkout");
231
172
 
232
- ### Vercel
233
-
234
- - **Edge Runtime**: Fast cold starts with identity context
235
- - **KV Storage**: Secure identity persistence using Vercel KV
236
- - **Zero Config**: Deploy with `vercel --prod` and identity works
237
- - **Environment**: Automatic identity configuration and key management
173
+ if (protection?.requiresDelegation) {
174
+ // Tool requires valid delegation token
175
+ }
176
+ ```
238
177
 
239
- ### AWS Lambda
178
+ ### Proof Generation
240
179
 
241
- - **Cold Start Optimized**: Minimal initialization with cached identity
242
- - **DynamoDB**: Secure identity storage with DynamoDB persistence
243
- - **Serverless**: Built-in serverless framework configuration
244
- - **IAM Integration**: Pre-configured identity and permission policies
180
+ Generate cryptographic proofs for tool responses:
245
181
 
246
- ### Next.js
182
+ ```typescript
183
+ import { ProofGenerator, createProofResponse } from "@kya-os/mcp-i";
247
184
 
248
- - **API Routes**: Identity-enabled API endpoints out of the box
249
- - **Middleware**: Request-level identity verification and delegation
250
- - **SSR Support**: Server-side identity rendering and verification
251
- - **Full Stack**: Complete client and server identity integration
185
+ const proofGenerator = new ProofGenerator(identity, clockProvider);
252
186
 
253
- ### Express
187
+ const proof = await proofGenerator.generateProof({
188
+ toolName: "get-weather",
189
+ input: { city: "London" },
190
+ output: { temperature: 20 },
191
+ sessionId: session.id,
192
+ nonce: session.nonce,
193
+ });
254
194
 
255
- - **Middleware Stack**: Identity verification middleware for existing apps
256
- - **Flexible Routing**: Identity-aware route handlers and permission checking
257
- - **Production Ready**: Battle-tested middleware for production workloads
258
- - **Custom Auth**: Extensible identity providers and authentication flows
195
+ // Create response with detached proof
196
+ const response = createProofResponse(toolOutput, proof);
197
+ ```
259
198
 
260
- ### Standalone
199
+ ### Session Management
261
200
 
262
- - **File Persistence**: Local identity storage with file-based backend
263
- - **Docker Ready**: Containerized deployment with identity intact
264
- - **Self Hosted**: Complete control over your agent and its identity
265
- - **Process Management**: PM2 and systemd configurations included
201
+ Handle MCP sessions with nonce protection:
266
202
 
267
- ## CLI Usage
203
+ ```typescript
204
+ import { SessionManager, createHandshakeRequest } from "@kya-os/mcp-i";
268
205
 
269
- ```bash
270
- # Development with identity features
271
- xmcp-i dev
206
+ const sessionManager = new SessionManager({
207
+ timestampSkewSeconds: 120,
208
+ ttlMinutes: 30,
209
+ });
272
210
 
273
- # Build for production deployment
274
- mcpi build
211
+ // Create handshake request
212
+ const request = createHandshakeRequest({
213
+ clientDid: "did:key:z6Mk...",
214
+ timestamp: Date.now(),
215
+ nonce: crypto.randomUUID(),
216
+ });
275
217
 
276
- # Platform-specific builds with identity optimization
277
- mcpi build --vercel
278
- mcpi build --lambda
279
- mcpi build --docker
218
+ // Validate and create session
219
+ const session = await sessionManager.createSession(request);
280
220
  ```
281
221
 
282
- ## Framework Integration
222
+ ### Well-Known Endpoints
283
223
 
284
- ### Agent Ownership in Action
224
+ Create standard MCP-I discovery endpoints:
285
225
 
286
226
  ```typescript
287
- import { createXMCPServer } from "@kya-os/xmcpi";
288
-
289
- // Create an agent with built-in cryptographic identity
290
- const agent = await createXMCPServer({
291
- name: "my-personal-agent",
292
- identity: {
293
- // Identity generated automatically with Ed25519 keys
294
- autoSign: true, // All responses signed with your key
295
- trustEndpoints: true, // Verification endpoints enabled
296
- persistence: "file", // Store identity securely
297
- },
298
- tools: [
299
- {
300
- name: "secure-action",
301
- description: "Execute action with verified identity",
302
- parameters: { action: { type: "string", required: true } },
303
- handler: async ({ action }, context) => {
304
- // Every response includes your cryptographic signature
305
- return {
306
- action: `Executed: ${action}`,
307
- agent_did: context.server.identity.did,
308
- owner: "you@knowthat.ai",
309
- timestamp: new Date().toISOString(),
310
- // ↑ This response is automatically signed with your private key
311
- };
312
- },
313
- },
314
- ],
315
- });
227
+ import { createWellKnownHandler } from "@kya-os/mcp-i";
316
228
 
317
- // Register your agent's DID with knowthat.ai to claim ownership
318
- await agent.register("https://knowthat.ai");
319
-
320
- agent.listen(3000, () => {
321
- console.log(`🤖 Your agent is running: ${agent.identity.did}`);
322
- console.log(
323
- `🔐 Claim ownership: https://knowthat.ai/claim/${agent.identity.did}`
324
- );
229
+ const handler = createWellKnownHandler({
230
+ identity,
231
+ serverUrl: "https://my-agent.example.com",
325
232
  });
233
+
234
+ // Handle requests to:
235
+ // - /.well-known/mcp-identity/health
236
+ // - /.well-known/mcp-identity/self
237
+ // - /.well-known/did.json
238
+ const response = await handler(pathname);
326
239
  ```
327
240
 
328
- ## Migrating from XMCP
241
+ ## Nonce Cache
329
242
 
330
- Your existing XMCP agents can gain ownership capabilities:
243
+ Prevent replay attacks with nonce caching:
331
244
 
332
245
  ```typescript
333
- // Before (original XMCP - platform owned)
334
- import { createXMCPServer } from "xmcp";
246
+ import {
247
+ MemoryNonceCache,
248
+ RedisNonceCache,
249
+ DynamoDBNonceCache,
250
+ CloudflareKVNonceCache,
251
+ } from "@kya-os/mcp-i";
335
252
 
336
- // After (XMCP-I - you own the agent!)
337
- import { createXMCPServer } from "xmcp-i";
338
- ```
253
+ // In-memory (development)
254
+ const cache = new MemoryNonceCache({ maxSize: 10000 });
339
255
 
340
- Your existing code works unchanged, but now your agent:
256
+ // Redis (production)
257
+ const cache = new RedisNonceCache({ url: process.env.REDIS_URL });
341
258
 
342
- - Has its own cryptographic identity
343
- - Can be registered and claimed by you at knowthat.ai
344
- - ✅ Signs all responses automatically
345
- - ✅ Supports secure permission delegation
346
- - ✅ Provides verifiable ownership proof
259
+ // DynamoDB (AWS)
260
+ const cache = new DynamoDBNonceCache({ tableName: "nonce-cache" });
261
+ ```
347
262
 
348
- ## Advanced Identity Features
263
+ ## Test Infrastructure
349
264
 
350
- ### Custom Identity Providers
265
+ For testing MCP-I integrations:
351
266
 
352
267
  ```typescript
353
- import { createCustomIdentityProvider } from "@kya-os/xmcpi/platforms";
354
-
355
- const customProvider = createCustomIdentityProvider({
356
- keyType: "secp256k1", // Alternative key types
357
- generateDID: (pubKey) => `did:custom:${hash(pubKey)}`,
358
- persistence: "redis", // Custom storage backends
359
- knowthat: {
360
- apiKey: process.env.KNOWTHAT_API_KEY,
361
- autoRegister: true, // Automatic agent registration
362
- },
268
+ import {
269
+ createTestEnvironment,
270
+ MockIdentityProvider,
271
+ deterministicKeys,
272
+ } from "@kya-os/mcp-i/test";
273
+
274
+ // Set XMCP_ENV=test to enable
275
+ const testEnv = await createTestEnvironment({
276
+ seed: "test-seed-123",
363
277
  });
364
278
 
365
- const agent = await createXMCPServer({
366
- name: "my-custom-agent",
367
- identity: { provider: customProvider },
368
- });
279
+ // Deterministic keys for reproducible tests
280
+ const identity = await deterministicKeys.generateIdentity("test-agent");
369
281
  ```
370
282
 
371
- ### Identity Middleware Integration
283
+ ## Environment Variables
372
284
 
373
- ```typescript
374
- import { identityMiddleware, delegationMiddleware } from "@kya-os/xmcpi";
375
-
376
- const agent = await createXMCPServer({
377
- name: "my-secure-agent",
378
- middlewares: [
379
- identityMiddleware({
380
- requireSignature: true, // Require signed requests
381
- trustLevel: "verified", // Only accept verified DIDs
382
- }),
383
- delegationMiddleware({
384
- checkPermissions: true, // Validate delegated permissions
385
- rateLimiting: true, // Enforce delegation rate limits
386
- }),
387
- ],
388
- });
389
- ```
390
-
391
- ## Dependencies and Architecture
392
-
393
- XMCP-I builds on proven cryptographic foundations:
394
-
395
- ### Core Identity Stack
285
+ | Variable | Description |
286
+ |----------|-------------|
287
+ | `AGENT_PRIVATE_KEY` | Base64-encoded Ed25519 private key (production) |
288
+ | `AGENT_KEY_ID` | Key ID for the agent |
289
+ | `AGENT_DID` | Agent's DID (production) |
290
+ | `AGENTSHIELD_API_KEY` | API key for AgentShield |
291
+ | `AGENTSHIELD_API_URL` | AgentShield API URL (default: `https://kya.vouched.id`) |
292
+ | `AGENTSHIELD_PROJECT_ID` | Project ID in AgentShield |
293
+ | `XMCP_ENV` | Set to `test` to enable test infrastructure |
396
294
 
397
- - **@kya-os/mcp-i** - Core identity protocol implementation with knowthat.ai integration
398
- - **jose** - JWT and cryptographic operations (JWS, JWE, JWK)
399
- - **@modelcontextprotocol/sdk** - MCP protocol SDK for agent communication
400
- - **axios** - HTTP client for identity resolution and knowthat.ai API calls
295
+ ## Platform Support
401
296
 
402
- ### Development Stack
297
+ This package is for **Node.js** environments. For other platforms:
403
298
 
404
- - **express** - Web server framework for identity endpoints
405
- - **webpack** - Module bundler with identity-aware compilation
406
- - **chalk** - Beautiful CLI output for identity operations
407
- - **chokidar** - File watching with identity file monitoring
299
+ | Platform | Package |
300
+ |----------|---------|
301
+ | Cloudflare Workers | `@kya-os/mcp-i-cloudflare` |
302
+ | Platform-agnostic core | `@kya-os/mcp-i-core` |
408
303
 
409
- ### Cryptographic Security
304
+ ## CLI Tools
410
305
 
411
- - **Ed25519** - Elliptic curve digital signatures (default)
412
- - **secp256k1** - Bitcoin-compatible signatures (optional)
413
- - **DID Keys** - Decentralized identifier generation from public keys
414
- - **JWS/JWE** - JSON Web Signatures and Encryption for secure transport
415
-
416
- ## Development
417
-
418
- Build your own identity-enabled MCP agents:
306
+ Use the `@kya-os/cli` package for command-line operations:
419
307
 
420
308
  ```bash
421
- # Clone the repository
422
- git clone https://github.com/modelcontextprotocol-identity/xmcp-i.git
423
-
424
- # Install dependencies
425
- pnpm install
426
-
427
- # Start development with identity features
428
- pnpm run dev
309
+ npm install -g @kya-os/cli
429
310
 
430
- # Build for production with identity optimization
431
- pnpm run build
311
+ # Initialize identity
312
+ mcpi init
432
313
 
433
- # Run identity-aware tests
434
- pnpm run test
314
+ # Check identity status
315
+ mcpi check
435
316
 
436
- # Lint code including identity modules
437
- pnpm run lint
317
+ # Rotate keys
318
+ mcpi rotate
438
319
  ```
439
320
 
440
- ## Learn more
321
+ ## Related Packages
441
322
 
442
- **Register Your Agent**: [knowthat.ai](https://knowthat.ai) - Claim ownership of your AI agents\
443
- **Original XMCP Framework**: [xmcp.dev](https://xmcp.dev) - Base framework documentation\
444
- **Model Context Protocol**: [modelcontextprotocol.io](https://modelcontextprotocol.io) - Core protocol specification
323
+ - [`@kya-os/create-mcpi-app`](https://www.npmjs.com/package/@kya-os/create-mcpi-app) - Project scaffolding
324
+ - [`@kya-os/mcp-i-cloudflare`](https://www.npmjs.com/package/@kya-os/mcp-i-cloudflare) - Cloudflare Workers runtime
325
+ - [`@kya-os/mcp-i-core`](https://www.npmjs.com/package/@kya-os/mcp-i-core) - Platform-agnostic core
326
+ - [`@kya-os/cli`](https://www.npmjs.com/package/@kya-os/cli) - CLI tools
327
+ - [`@kya-os/contracts`](https://www.npmjs.com/package/@kya-os/contracts) - Shared types and schemas
445
328
 
446
- ## Security
329
+ ## Learn More
447
330
 
448
- If you believe you have found a security vulnerability, please report it to [security@xmcp-i.dev](mailto:security@xmcp-i.dev). We take agent ownership security seriously and will investigate all reports promptly.
331
+ - [MCP-I Documentation](https://github.com/modelcontextprotocol-identity/xmcp-i) - Full framework documentation
332
+ - [Model Context Protocol](https://modelcontextprotocol.io) - Core protocol specification
333
+ - [Know That AI](https://knowthat.ai) - Agent registration and claims
449
334
 
450
335
  ## License
451
336
 
452
- This project is licensed under the MIT License - see the [LICENSE](https://github.com/modelcontextprotocol-identity/xmcp-i/blob/main/license.md) file for details.
337
+ MIT License - see [LICENSE](https://github.com/modelcontextprotocol-identity/xmcp-i/blob/main/license.md)