@kya-os/mcp-i/README.md

The TypeScript MCP framework with identity features built-in

<div align="center">
  <a href="https://github.com/modelcontextprotocol-identity/xmcp-i">
    <picture>
      <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/modelcontextprotocol-identity/xmcp-i/main/assets/mcp-i-logo-dark.png">
      <img alt="MCP-I logo" src="https://raw.githubusercontent.com/modelcontextprotocol-identity/xmcp-i/main/assets/mcp-i-logo-light.png" height="128">
    </picture>
  </a>
  <h1>xmcp-i</h1>

<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>
<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>
<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>

</div>

## Own Your AI Agent with Cryptographic Identity

`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.

## Quick Start

Create your first owned AI agent:

```bash
npx @kya-os/create-xmcpi-app@latest my-agent
```

Then register and claim ownership at [knowthat.ai](https://knowthat.ai)

> **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.

## Installation

### For New Projects

```bash
npx create-xmcpi-app@latest my-agent
```

### For Existing Projects

```bash
npx init-xmcp-i@latest
```

This will add identity features to your existing Node.js/TypeScript project with automatic framework detection and configuration.

## Why Agent Ownership Matters

⊹ **True Ownership** - Your agent belongs to you, not a platform\
⊹ **Cryptographic Security** - Ed25519 keys and DID-based identity\
⊹ **Permission Control** - Delegate and revoke capabilities securely\
⊹ **Verifiable Actions** - All responses are cryptographically signed\
⊹ **Decentralized Trust** - No central authority controls your agent\
⊹ **Portable Identity** - Move your agent between platforms while keeping ownership

### Cryptographic Foundation

- **DID Generation**: Decentralized identifiers from public keys
- **Automatic Signing**: All responses signed with your private key
- **Key Security**: Private keys never leave your control

## Security and Trust

**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.

**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.

**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.

## Real-World Benefits for Developers & Businesses

### Privacy-First Tracking & Analytics

Unlike traditional web tracking (cookies, pixels), XMCP-I provides **ethical data collection**:

- Users can see exactly what data is stored about them
- Users can revoke access instantly at any time
- Businesses get analytics for retargeting without violating privacy
- Think "GDPR-compliant by design" - users control their data completely

### XMCP-I Allows AI in Regulated Industries

Industries like healthcare, law, and finance can now use AI while maintaining compliance:

**The Problem**: These industries need AI efficiency but can't use most AI services due to:

- Data privacy regulations (HIPAA, GDPR, SOX)
- Audit requirements (who did what, when?)
- Client confidentiality obligations

**The Solution**: XMCP-I provides:

- **Provable Privacy**: Cryptographic proof of data handling
- **Complete Audit Trails**: Every AI action is signed and traceable
- **User Control**: Clients can revoke AI access to their data instantly
- **Regulatory Compliance**: Built-in features for GDPR, HIPAA, etc.
- **EU AI Act Compliance**: Built-in audit trails and user consent mechanisms

**Real Example**: A law firm can now use AI for document review because:

- Clients control exactly which documents the AI can access
- All AI actions are cryptographically logged
- Clients can revoke access immediately if they switch firms
- The firm can prove to regulators exactly how data was handled

## Installation

### For New Projects

```bash
npx @kya-os/create-xmcpi-app@latest my-agent
```

### For Existing Projects

```bash
npm install @kya-os/xmcpi
# or
yarn add @kya-os/xmcpi
# or
pnpm add @kya-os/xmcpi
```

## Migrating from XMCP

Your existing XMCP agents can gain ownership capabilities:

```typescript
// Before (original XMCP - platform owned)
import { createXMCPServer } from "xmcp";

// After (XMCP-I - you own the agent!)
import { createXMCPServer } from "xmcp-i";
```

Your existing code works unchanged, but now your agent:

- ✅ Has its own cryptographic identity
- ✅ Can be registered and claimed by you at knowthat.ai
- ✅ Signs all responses automatically
- ✅ Supports secure permission delegation
- ✅ Provides verifiable ownership proof

## Core Identity Features

### Agent Identity Verification

Your agent provides cryptographic proof of ownership:

```bash
# Your agent's identity includes:
{
  "did": "did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK",
  "publicKey": "-----BEGIN PUBLIC KEY-----\n...",
  "privateKey": "-----BEGIN PRIVATE KEY-----\n...",  // Never shared
  "agentId": "agent-abc123...",
  "capabilities": {
    "tools": true,
    "signing": true,
    "verification": true,
    "delegation": true
  }
}
```

- **Public Key**: Can be shared and verified by anyone
- **Private Key**: Never leaves your control, stored securely locally
- **DID**: Globally unique identifier generated from your public key
- **Signatures**: All agent responses include cryptographic signatures

### Trust Infrastructure

- `GET /.well-known/mcp-identity/health` - Health check with identity
- `GET /.well-known/mcp-identity/self` - Agent identity information
- `POST /.well-known/mcp-identity/verify` - Verify signatures
- `GET /.well-known/mcp-identity/resolve/:did` - Resolve DIDs

### Built-in Identity Tools & Self-Sovereign Features

- `get-identity-info` - Comprehensive agent identity details
- `sign-message` - Sign messages with your private key
- `verify-signature` - Verify signatures against DIDs
- `get-server-status` - Agent status with identity information
- `get-user-data` - Allow users to see all stored data about them
- `revoke-user-access` - Let users instantly revoke AI access to their data
- `export-user-data` - Enable users to export their data for portability

## Secure Permission Delegation

Control what your agent can do and for whom:

```typescript
// Delegate specific permissions to other DIDs
await agent.delegate({
  to: "did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK",
  permissions: ["read:data", "execute:safe-actions"],
  expires: new Date("2025-12-31"),
  conditions: {
    rate_limit: "100/hour",
    allowed_tools: ["get-weather", "search-docs"],
  },
});

// Revoke permissions instantly
await agent.revoke({
  delegation_id: "del_abc123",
  reason: "Project completed",
});

// All delegation changes are cryptographically signed and verifiable
```

### Secure Delegation Example

Grant specific permissions to other users while maintaining ownership:

```typescript
// Example: Grant read-only access to specific tools
await agent.delegate({
  to: "user@example.com",
  permissions: ["read:weather", "read:docs"],
  expires: "2025-12-31T23:59:59Z",
  conditions: { rate_limit: "100/hour" },
});
```

## Platform Support with Identity Persistence

Deploy your owned agents anywhere with secure identity storage:

### Vercel

- **Edge Runtime**: Fast cold starts with identity context
- **KV Storage**: Secure identity persistence using Vercel KV
- **Zero Config**: Deploy with `vercel --prod` and identity works
- **Environment**: Automatic identity configuration and key management

### AWS Lambda

- **Cold Start Optimized**: Minimal initialization with cached identity
- **DynamoDB**: Secure identity storage with DynamoDB persistence
- **Serverless**: Built-in serverless framework configuration
- **IAM Integration**: Pre-configured identity and permission policies

### Next.js

- **API Routes**: Identity-enabled API endpoints out of the box
- **Middleware**: Request-level identity verification and delegation
- **SSR Support**: Server-side identity rendering and verification
- **Full Stack**: Complete client and server identity integration

### Express

- **Middleware Stack**: Identity verification middleware for existing apps
- **Flexible Routing**: Identity-aware route handlers and permission checking
- **Production Ready**: Battle-tested middleware for production workloads
- **Custom Auth**: Extensible identity providers and authentication flows

### Standalone

- **File Persistence**: Local identity storage with file-based backend
- **Docker Ready**: Containerized deployment with identity intact
- **Self Hosted**: Complete control over your agent and its identity
- **Process Management**: PM2 and systemd configurations included

## CLI Usage

```bash
# Development with identity features
xmcp-i dev

# Build for production deployment
mcpi build

# Platform-specific builds with identity optimization
mcpi build --vercel
mcpi build --lambda
mcpi build --docker
```

## Framework Integration

### Agent Ownership in Action

```typescript
import { createXMCPServer } from "@kya-os/xmcpi";

// Create an agent with built-in cryptographic identity
const agent = await createXMCPServer({
  name: "my-personal-agent",
  identity: {
    // Identity generated automatically with Ed25519 keys
    autoSign: true, // All responses signed with your key
    trustEndpoints: true, // Verification endpoints enabled
    persistence: "file", // Store identity securely
  },
  tools: [
    {
      name: "secure-action",
      description: "Execute action with verified identity",
      parameters: { action: { type: "string", required: true } },
      handler: async ({ action }, context) => {
        // Every response includes your cryptographic signature
        return {
          action: `Executed: ${action}`,
          agent_did: context.server.identity.did,
          owner: "you@knowthat.ai",
          timestamp: new Date().toISOString(),
          // ↑ This response is automatically signed with your private key
        };
      },
    },
  ],
});

// Register your agent's DID with knowthat.ai to claim ownership
await agent.register("https://knowthat.ai");

agent.listen(3000, () => {
  console.log(`🤖 Your agent is running: ${agent.identity.did}`);
  console.log(
    `🔐 Claim ownership: https://knowthat.ai/claim/${agent.identity.did}`
  );
});
```

## Migrating from XMCP

Your existing XMCP agents can gain ownership capabilities:

```typescript
// Before (original XMCP - platform owned)
import { createXMCPServer } from "xmcp";

// After (XMCP-I - you own the agent!)
import { createXMCPServer } from "xmcp-i";
```

Your existing code works unchanged, but now your agent:

- ✅ Has its own cryptographic identity
- ✅ Can be registered and claimed by you at knowthat.ai
- ✅ Signs all responses automatically
- ✅ Supports secure permission delegation
- ✅ Provides verifiable ownership proof

## Advanced Identity Features

### Custom Identity Providers

```typescript
import { createCustomIdentityProvider } from "@kya-os/xmcpi/platforms";

const customProvider = createCustomIdentityProvider({
  keyType: "secp256k1", // Alternative key types
  generateDID: (pubKey) => `did:custom:${hash(pubKey)}`,
  persistence: "redis", // Custom storage backends
  knowthat: {
    apiKey: process.env.KNOWTHAT_API_KEY,
    autoRegister: true, // Automatic agent registration
  },
});

const agent = await createXMCPServer({
  name: "my-custom-agent",
  identity: { provider: customProvider },
});
```

### Identity Middleware Integration

```typescript
import { identityMiddleware, delegationMiddleware } from "@kya-os/xmcpi";

const agent = await createXMCPServer({
  name: "my-secure-agent",
  middlewares: [
    identityMiddleware({
      requireSignature: true, // Require signed requests
      trustLevel: "verified", // Only accept verified DIDs
    }),
    delegationMiddleware({
      checkPermissions: true, // Validate delegated permissions
      rateLimiting: true, // Enforce delegation rate limits
    }),
  ],
});
```

## Dependencies and Architecture

XMCP-I builds on proven cryptographic foundations:

### Core Identity Stack

- **@kya-os/mcp-i** - Core identity protocol implementation with knowthat.ai integration
- **jose** - JWT and cryptographic operations (JWS, JWE, JWK)
- **@modelcontextprotocol/sdk** - MCP protocol SDK for agent communication
- **axios** - HTTP client for identity resolution and knowthat.ai API calls

### Development Stack

- **express** - Web server framework for identity endpoints
- **webpack** - Module bundler with identity-aware compilation
- **chalk** - Beautiful CLI output for identity operations
- **chokidar** - File watching with identity file monitoring

### Cryptographic Security

- **Ed25519** - Elliptic curve digital signatures (default)
- **secp256k1** - Bitcoin-compatible signatures (optional)
- **DID Keys** - Decentralized identifier generation from public keys
- **JWS/JWE** - JSON Web Signatures and Encryption for secure transport

## Development

Build your own identity-enabled MCP agents:

```bash
# Clone the repository
git clone https://github.com/modelcontextprotocol-identity/xmcp-i.git

# Install dependencies
pnpm install

# Start development with identity features
pnpm run dev

# Build for production with identity optimization
pnpm run build

# Run identity-aware tests
pnpm run test

# Lint code including identity modules
pnpm run lint
```

## Learn more

⊹ **Register Your Agent**: [knowthat.ai](https://knowthat.ai) - Claim ownership of your AI agents\
⊹ **Original XMCP Framework**: [xmcp.dev](https://xmcp.dev) - Base framework documentation\
⊹ **Model Context Protocol**: [modelcontextprotocol.io](https://modelcontextprotocol.io) - Core protocol specification

## Security

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.

## License

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.