npm package: @protocol-embedded-compliance/mastra
Description: Protocol-Embedded Compliance (PEC) integration for Mastra AI agents
Author: Lloyd Jones
Latest version: 0.1.0

# @protocol-embedded-compliance/mastra

Protocol-Embedded Compliance (PEC) integration for [Mastra](https://mastra.ai) AI agents.

## What is PEC?

Protocol-Embedded Compliance embeds regulatory requirements into AI agent-tool interactions. MCP servers declare compliance metadata, deployers specify constraints, and agents filter tools automatically.

## What is this package?

An **MCPClient wrapper** that:
1. Connects to MCP servers
2. Discovers tools with embedded PEC metadata
3. Filters against your deployment context
4. Returns only compliant tools

## Installation

```bash
pnpm add @protocol-embedded-compliance/mastra @mastra/mcp
```

## Quick Start

```typescript
import { PecMCPClient, euGeneralContext } from '@protocol-embedded-compliance/mastra'

const client = new PecMCPClient({
  servers: {
    myServer: {
      command: 'npx',
      args: ['my-mcp-server']
    }
  }
})

const { compliant, rejected } = await client.getCompliantTools(euGeneralContext)

console.log(`${compliant.length} tools available, ${rejected.length} filtered out`)

for (const tool of compliant) {
  console.log(`✓ ${tool.name} (${tool.compliance.processing_locations.join(', ')})`)
}

await client.disconnect()
```

## API

### `PecMCPClient`

Wraps Mastra's `MCPClient` with PEC filtering.

```typescript
const client = new PecMCPClient({
  servers: {
    // Same config as @mastra/mcp MCPClient
  }
})

// Discover all tools and parse PEC metadata
const { all, withMetadata, withoutMetadata } = await client.discoverTools()

// Get only compliant tools for a deployment context
const { compliant, rejected } = await client.getCompliantTools(context)

// Access raw MCPClient tools (no filtering)
const rawTools = await client.getRawTools()

// Disconnect
await client.disconnect()
```

### `filterCompliantTools()`

Filter any array of tools with PEC metadata:

```typescript
import { filterCompliantTools, euGeneralContext } from '@protocol-embedded-compliance/mastra'

const tools = [
  { name: 'tool1', compliance: { /* PEC metadata */ }, tool: actualTool1 },
  { name: 'tool2', compliance: { /* PEC metadata */ }, tool: actualTool2 }
]

const { compliant, rejected } = filterCompliantTools(tools, euGeneralContext)
```

### `checkCompliance()`

Check a single tool's compliance:

```typescript
import { checkCompliance, euGeneralContext } from '@protocol-embedded-compliance/mastra'

const result = checkCompliance(toolMetadata, euGeneralContext)
// { compliant: boolean, reasons: string[], warnings: string[] }
```

## Preset Contexts

```typescript
import {
  euGeneralContext,      // EU, max risk: limited, no US/CN/RU
  euHealthcareContext,   // EU healthcare, special categories allowed
  usHealthcareContext    // US, HIPAA required, no CN/RU/IR/KP
} from '@protocol-embedded-compliance/mastra'
```

## Custom Deployment Context

```typescript
import type { DeploymentContext } from '@protocol-embedded-compliance/mastra'

const myContext: DeploymentContext = {
  governing_law: 'EU',
  jurisdiction: 'FR',
  data_residency: {
    required: ['EU', 'EEA'],
    prohibited: ['US', 'CN']
  },
  gdpr_requirements: {
    transfer_mechanisms_required: ['ADEQUACY', 'SCCS_2021'],
    special_categories_allowed: false
  },
  risk_classification: {
    maximum_permitted: 'limited'
  },
  sectors: {
    prohibited: ['military']
  },
  certifications: {
    required_any: ['ISO_27001']
  }
}
```

## How MCP Servers Embed PEC Metadata

Servers embed PEC metadata in tool descriptions:

```typescript
const description = `Summarises documents.

[PEC_COMPLIANCE:{"pec_version":"1.0","processing_locations":["DE","IE"],...}]`
```

See the [PEC Example](https://github.com/Protocol-Embedded-Compliance/example) for a complete implementation.

## Filtering Checks

| Check | Description |
|-------|-------------|
| Location | Tool's processing locations vs required/prohibited |
| Risk | AI Act classification vs maximum permitted |
| Conformity | Whether tool has undergone conformity assessment |
| GDPR Transfer | Required transfer mechanisms for EU |
| Special Categories | Art 9 data processing restrictions |
| Certifications | Required certifications (HIPAA, ISO 27001, etc.) |
| Sectors | Prohibited use cases |

## Learn More

- [PEC Website](https://usepec.eu)
- [PEC Example Project](https://github.com/Protocol-Embedded-Compliance/example)
- [Mastra Documentation](https://mastra.ai/docs)
- [MCP Specification](https://modelcontextprotocol.io/)

## Licence

MIT