@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.
- package/README.md +218 -333
- package/dist/114.js +1 -0
- package/dist/139.js +1 -0
- package/dist/200.js +1 -0
- package/dist/202.js +1 -0
- package/dist/238.js +1 -0
- package/dist/263.js +1 -0
- package/dist/294.js +1 -0
- package/dist/295.js +1 -1
- package/dist/374.js +1 -0
- package/dist/529.js +1 -0
- package/dist/627.js +1 -0
- package/dist/644.js +1 -0
- package/dist/669.js +1 -0
- package/dist/857.js +1 -0
- package/dist/866.js +1 -1
- package/dist/{941.js → 966.js} +1 -1
- package/dist/997.js +1 -0
- package/dist/providers/node-providers.d.ts +1 -1
- package/dist/providers/node-providers.js +2 -2
- package/dist/runtime/adapter-express.js +5 -5
- package/dist/runtime/adapter-express.js.LICENSE.txt +0 -7
- package/dist/runtime/adapter-nextjs.js +6 -6
- package/dist/runtime/adapter-nextjs.js.LICENSE.txt +0 -189
- package/dist/runtime/auth-handshake.d.ts +4 -159
- package/dist/runtime/auth-handshake.js +8 -249
- package/dist/runtime/http.js +5 -5
- package/dist/runtime/http.js.LICENSE.txt +0 -7
- package/dist/runtime/mcpi-runtime.d.ts +4 -0
- package/dist/runtime/mcpi-runtime.js +58 -43
- package/dist/runtime/outbound-delegation.d.ts +34 -0
- package/dist/runtime/outbound-delegation.js +134 -0
- package/dist/runtime/proof.d.ts +13 -88
- package/dist/runtime/proof.js +11 -225
- package/dist/runtime/request-context.d.ts +41 -0
- package/dist/runtime/request-context.js +48 -0
- package/dist/runtime/session.d.ts +13 -104
- package/dist/runtime/session.js +31 -267
- package/dist/runtime/stdio.js +6 -7
- package/dist/runtime/utils/server.d.ts +2 -8
- package/dist/runtime/utils/tools.js +17 -3
- package/dist/storage/delegation.js +2 -2
- package/package.json +32 -31
- package/dist/207.js +0 -1
- package/dist/25.js +0 -1
- package/dist/387.js +0 -1
- package/dist/406.js +0 -1
- package/dist/448.js +0 -1
- package/dist/478.js +0 -1
- package/dist/482.js +0 -1
- package/dist/575.js +0 -1
- package/dist/67.js +0 -1
- package/dist/743.js +0 -1
- package/dist/784.js +0 -1
- package/dist/844.js +0 -1
- package/dist/936.js +0 -1
- package/dist/988.js +0 -1
- 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
|
|
8
|
+
<h1>@kya-os/mcp-i</h1>
|
|
9
9
|
|
|
10
|
-
<a href="https://github.com/modelcontextprotocol-identity/xmcp-i"><img alt="
|
|
11
|
-
<a href="https://www.npmjs.com/package/
|
|
12
|
-
<a href="https://github.com/modelcontextprotocol-identity/xmcp-i/blob/main/license.md"><img alt="License" src="https://img.shields.io/npm/l/
|
|
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
|
-
##
|
|
16
|
+
## Node.js Runtime for MCP-I
|
|
17
17
|
|
|
18
|
-
|
|
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-
|
|
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
|
-
|
|
35
|
+
npm install @kya-os/mcp-i
|
|
44
36
|
```
|
|
45
37
|
|
|
46
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
50
|
+
### CLI Identity Setup
|
|
64
51
|
|
|
65
|
-
|
|
52
|
+
Initialize identity for CLI tools and development:
|
|
66
53
|
|
|
67
|
-
|
|
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
|
-
|
|
89
|
-
-
|
|
90
|
-
|
|
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
|
-
|
|
65
|
+
console.log(`Agent DID: ${result.identity.did}`);
|
|
66
|
+
console.log(`Claim URL: ${result.metadata.claimUrl}`);
|
|
67
|
+
```
|
|
93
68
|
|
|
94
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
83
|
+
Direct identity management for runtime use:
|
|
108
84
|
|
|
109
|
-
|
|
85
|
+
```typescript
|
|
86
|
+
import { IdentityManager, type AgentIdentity } from "@kya-os/mcp-i";
|
|
110
87
|
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
88
|
+
const manager = new IdentityManager({
|
|
89
|
+
environment: "development",
|
|
90
|
+
devIdentityPath: ".mcpi/identity.json",
|
|
91
|
+
});
|
|
114
92
|
|
|
115
|
-
|
|
93
|
+
// Load or generate identity
|
|
94
|
+
const identity: AgentIdentity = await manager.ensureIdentity();
|
|
116
95
|
|
|
117
|
-
|
|
118
|
-
|
|
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
|
-
|
|
100
|
+
### MCP-I Runtime
|
|
126
101
|
|
|
127
|
-
|
|
102
|
+
Create a full MCP-I runtime with all providers:
|
|
128
103
|
|
|
129
104
|
```typescript
|
|
130
|
-
|
|
131
|
-
import { createXMCPServer } from "xmcp";
|
|
105
|
+
import { createMCPIRuntime } from "@kya-os/mcp-i";
|
|
132
106
|
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
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
|
-
|
|
118
|
+
// Handle MCP handshake
|
|
119
|
+
const handshakeResult = await runtime.handleHandshake(request);
|
|
150
120
|
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
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
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
142
|
+
const result = await verifier.verify({
|
|
143
|
+
delegationToken: token,
|
|
144
|
+
requiredScopes: ["checkout:execute"],
|
|
145
|
+
agentDid: runtime.getIdentity().did,
|
|
209
146
|
});
|
|
210
147
|
|
|
211
|
-
|
|
148
|
+
if (result.valid) {
|
|
149
|
+
console.log("Delegation verified:", result.delegationId);
|
|
150
|
+
}
|
|
212
151
|
```
|
|
213
152
|
|
|
214
|
-
###
|
|
153
|
+
### Tool Protection
|
|
215
154
|
|
|
216
|
-
|
|
155
|
+
Configure which tools require delegation:
|
|
217
156
|
|
|
218
157
|
```typescript
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
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
|
-
|
|
170
|
+
const resolver = new ToolProtectionResolver([source]);
|
|
171
|
+
const protection = await resolver.getProtection("checkout");
|
|
231
172
|
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
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
|
-
###
|
|
178
|
+
### Proof Generation
|
|
240
179
|
|
|
241
|
-
|
|
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
|
-
|
|
182
|
+
```typescript
|
|
183
|
+
import { ProofGenerator, createProofResponse } from "@kya-os/mcp-i";
|
|
247
184
|
|
|
248
|
-
|
|
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
|
-
|
|
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
|
-
|
|
256
|
-
|
|
257
|
-
|
|
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
|
-
###
|
|
199
|
+
### Session Management
|
|
261
200
|
|
|
262
|
-
|
|
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
|
-
|
|
203
|
+
```typescript
|
|
204
|
+
import { SessionManager, createHandshakeRequest } from "@kya-os/mcp-i";
|
|
268
205
|
|
|
269
|
-
|
|
270
|
-
|
|
271
|
-
|
|
206
|
+
const sessionManager = new SessionManager({
|
|
207
|
+
timestampSkewSeconds: 120,
|
|
208
|
+
ttlMinutes: 30,
|
|
209
|
+
});
|
|
272
210
|
|
|
273
|
-
|
|
274
|
-
|
|
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
|
-
|
|
277
|
-
|
|
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
|
-
|
|
222
|
+
### Well-Known Endpoints
|
|
283
223
|
|
|
284
|
-
|
|
224
|
+
Create standard MCP-I discovery endpoints:
|
|
285
225
|
|
|
286
226
|
```typescript
|
|
287
|
-
import {
|
|
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
|
-
|
|
318
|
-
|
|
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
|
-
##
|
|
241
|
+
## Nonce Cache
|
|
329
242
|
|
|
330
|
-
|
|
243
|
+
Prevent replay attacks with nonce caching:
|
|
331
244
|
|
|
332
245
|
```typescript
|
|
333
|
-
|
|
334
|
-
|
|
246
|
+
import {
|
|
247
|
+
MemoryNonceCache,
|
|
248
|
+
RedisNonceCache,
|
|
249
|
+
DynamoDBNonceCache,
|
|
250
|
+
CloudflareKVNonceCache,
|
|
251
|
+
} from "@kya-os/mcp-i";
|
|
335
252
|
|
|
336
|
-
//
|
|
337
|
-
|
|
338
|
-
```
|
|
253
|
+
// In-memory (development)
|
|
254
|
+
const cache = new MemoryNonceCache({ maxSize: 10000 });
|
|
339
255
|
|
|
340
|
-
|
|
256
|
+
// Redis (production)
|
|
257
|
+
const cache = new RedisNonceCache({ url: process.env.REDIS_URL });
|
|
341
258
|
|
|
342
|
-
|
|
343
|
-
|
|
344
|
-
|
|
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
|
-
##
|
|
263
|
+
## Test Infrastructure
|
|
349
264
|
|
|
350
|
-
|
|
265
|
+
For testing MCP-I integrations:
|
|
351
266
|
|
|
352
267
|
```typescript
|
|
353
|
-
import {
|
|
354
|
-
|
|
355
|
-
|
|
356
|
-
|
|
357
|
-
|
|
358
|
-
|
|
359
|
-
|
|
360
|
-
|
|
361
|
-
|
|
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
|
-
|
|
366
|
-
|
|
367
|
-
identity: { provider: customProvider },
|
|
368
|
-
});
|
|
279
|
+
// Deterministic keys for reproducible tests
|
|
280
|
+
const identity = await deterministicKeys.generateIdentity("test-agent");
|
|
369
281
|
```
|
|
370
282
|
|
|
371
|
-
|
|
283
|
+
## Environment Variables
|
|
372
284
|
|
|
373
|
-
|
|
374
|
-
|
|
375
|
-
|
|
376
|
-
|
|
377
|
-
|
|
378
|
-
|
|
379
|
-
|
|
380
|
-
|
|
381
|
-
|
|
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
|
-
|
|
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
|
-
|
|
297
|
+
This package is for **Node.js** environments. For other platforms:
|
|
403
298
|
|
|
404
|
-
|
|
405
|
-
|
|
406
|
-
|
|
407
|
-
|
|
299
|
+
| Platform | Package |
|
|
300
|
+
|----------|---------|
|
|
301
|
+
| Cloudflare Workers | `@kya-os/mcp-i-cloudflare` |
|
|
302
|
+
| Platform-agnostic core | `@kya-os/mcp-i-core` |
|
|
408
303
|
|
|
409
|
-
|
|
304
|
+
## CLI Tools
|
|
410
305
|
|
|
411
|
-
|
|
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
|
-
|
|
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
|
-
#
|
|
431
|
-
|
|
311
|
+
# Initialize identity
|
|
312
|
+
mcpi init
|
|
432
313
|
|
|
433
|
-
#
|
|
434
|
-
|
|
314
|
+
# Check identity status
|
|
315
|
+
mcpi check
|
|
435
316
|
|
|
436
|
-
#
|
|
437
|
-
|
|
317
|
+
# Rotate keys
|
|
318
|
+
mcpi rotate
|
|
438
319
|
```
|
|
439
320
|
|
|
440
|
-
##
|
|
321
|
+
## Related Packages
|
|
441
322
|
|
|
442
|
-
|
|
443
|
-
|
|
444
|
-
|
|
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
|
-
##
|
|
329
|
+
## Learn More
|
|
447
330
|
|
|
448
|
-
|
|
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
|
-
|
|
337
|
+
MIT License - see [LICENSE](https://github.com/modelcontextprotocol-identity/xmcp-i/blob/main/license.md)
|