feat: TypeScript Cedar schema generation from MCP tool descriptions (protect-mcp)

[tomjwxf]

Summary

Adds a TypeScript integration example showing how to auto-generate Cedar authorization schemas from MCP tool descriptions, enabling typed policies for runtime tool governance.

This builds on the discussion in cedar-policy/cedar#2266, where @lianah recommended integrating the cedar-policy-mcp-schema-generator and using static schemas with Cedar for validation. This example provides a TypeScript-native path for Node.js environments where the Rust binary is not available.

What this adds

js/protect-mcp-cedar-integration/ — a working example with:

File	Purpose
README.md	Documentation with type mapping table, example policies, compatibility notes
example.mjs	Runnable demo: generates Cedar schema from 5 MCP tools
test.mjs	14 tests covering type mapping, structure, edge cases
policies/mcp-governance.cedar	Example policies using the generated schema
package.json	Depends on protect-mcp (npm, MIT)

How it works

import { generateCedarSchema } from 'protect-mcp';

const tools = [
  { name: 'read_file', inputSchema: { type: 'object', properties: { path: { type: 'string' } }, required: ['path'] } },
  { name: 'execute_command', inputSchema: { type: 'object', properties: { command: { type: 'string' } }, required: ['command'] } },
];

const schema = generateCedarSchema(tools);
// schema.schemaText → human-readable .cedarschema
// schema.schemaJson → JSON for Cedar WASM isAuthorized()

This enables typed policies:

permit(principal, action == Action::"read_file", resource)
when { context.input.path like "./workspace/*" };

Compatibility with the Rust generator

• Same entity model: Agent (principal), Tool (resource)
• Same action hierarchy: per-tool actions as children of MCP::Tool::call
• Same JSON Schema → Cedar type mapping
• Schema stubs use @mcp_principal / @mcp_resource annotations
• The TypeScript version covers the common MCP use case; the Rust generator provides additional features (union types, tagged entities, output schemas)

Context

protect-mcp (v0.5.2, MIT) is a security gateway for MCP servers and Claude Code that uses Cedar WASM for runtime policy enforcement. Every allow/deny decision produces an Ed25519-signed receipt following the IETF Internet-Draft format.

This PR was motivated by @lianah's recommendation in cedar-policy/cedar#2266 to move from schema: null to validated schemas and to integrate with the cedar-for-agents schema generation tooling.

[lianah]

Thank you for your contribution! It's great to see increased adoption of Cedar for agents. One concern we have with the approach of re-implementing the schema generator code in TypeScript is that the two implementations might diverge, and we would want to have consistent behavior across the two languages. Something we have done in the past is WASM bindings for the Rust code. Would this work for your use case or are there any reasons why that is not a good fit?

There are a couple of corner cases in the current schema generator we had to be careful about handling correctly that we would want to make sure are consistent across the two versions:

• JSON number can actually be either int or float, so representing it as Long won't be the same behavior. Cedar does not support float so we have an option to model it as decimal. See this code comment for details
• Modeling objects as entities vs records. Records are nice because they support structural equality, but they do not support tags. In the JSON schema there is this notion of additionalProperties that our generator models as Cedar tags so for those types we use entities. See the code here
• Reusing record/entity types between sub-objects: the Rust schema generator introduces names and namespaces for the JSON objects based on the field name to avoid conflicts e.g. if multiple MCP tools have the same address field but with different structures

There is also some work on utility code to map from the actual MCP tool inputs to a Cedar request to make integration easier.

[tomjwxf]

@lianah -- you are right. Implementation divergence is the real risk here, and the three edge cases you flagged (number/float handling, additionalProperties as tagged entities, and namespaced type deduplication) are exactly the places where a TypeScript reimplementation would silently produce different schemas.

WASM bindings for the Rust generator is the better path. I checked and the crate does not have wasm-bindgen today -- would it be useful if I contributed WASM bindings as a PR to the schema generator crate? The scope would be:

1. Add wasm-bindgen to cedar-policy-mcp-schema-generator
2. Expose SchemaGenerator and RequestGenerator to JavaScript/TypeScript via WASM
3. Publish as an npm package (something like @cedar-policy/mcp-schema-generator-wasm)
4. Update this PR to use the WASM bindings instead of the TypeScript reimplementation

This way protect-mcp (and any other TypeScript/Node.js MCP tool) gets the exact same behavior as the Rust generator, including all the edge cases around decimal encoding, entity vs record modeling, and namespace deduplication.

I am already using @cedar-policy/cedar-wasm (v4.9.1) for policy evaluation in protect-mcp, so the WASM integration pattern is familiar. Happy to start on this if the approach works for you.

On the utility code for mapping MCP tool inputs to Cedar requests -- I built a basic version of this in protect-mcp (maps tool_name to resource, agent tier to principal, tool input to context). Would be glad to align it with whatever interface the Rust RequestGenerator exposes through WASM.

[tomjwxf]

@lianah -- I built the WASM bindings as a proof-of-concept and they work. Here is a working demo:

WASM crate: `cedar-policy-mcp-schema-generator-wasm` -- a thin `wasm-bindgen` wrapper around the existing Rust `SchemaGenerator`.

What it exposes to JavaScript/TypeScript:

```js
import { generateSchema, WasmSchemaConfig } from 'cedar-policy-mcp-schema-generator-wasm';

const result = generateSchema(stubCedarSchema, toolsJson, configJson);
// result.schema -> Cedar schema as human-readable text
// result.error -> null if successful
// result.isOk -> boolean
```

Tested in Node.js -- produces correct output:

```
namespace MyServer {
type execute_commandInput = {
command: String,
timeout?: Long
};

type read_fileInput = {
encoding?: String,
path: String
};

entity McpServer;
entity User = { id: String };

action "call_tool";
action "execute_command" in [Action::"call_tool"] appliesTo {
principal: [User],
resource: [McpServer],
context: { input: execute_commandInput }
};
action "read_file" in [Action::"call_tool"] appliesTo {
principal: [User],
resource: [McpServer],
context: { input: read_fileInput }
};
}
```

Implementation details:

• Parses schema stub via `Fragment::from_cedarschema_str`
• Parses tool descriptions via `ServerDescription::from_json_str`
• Exposes all `SchemaGeneratorConfig` options (include_outputs, objects_as_records, flatten_namespaces, numbers_as_decimal, erase_annotations)
• Required `uuid` `js` feature + `getrandom` `wasm_js` feature for WASM compat
• 2.5MB WASM binary (could be reduced with wasm-opt and feature gating)
• 3 Rust tests passing

Two options for how to proceed:

1. I can submit this as a PR to this repo adding `rust/cedar-policy-mcp-schema-generator-wasm/` alongside the existing crates. The cedar-for-agents team would own and publish it.

2. I can publish it independently and update my original PR (feat: TypeScript Cedar schema generation from MCP tool descriptions (protect-mcp) #63) to use the WASM bindings instead of the TypeScript reimplementation.

Which approach works better for the cedar-for-agents project? Happy to do either.

[lianah]

That's awesome! I think submitting the WASM bindings as a PR against the cedar-for-agents repo under rust/cedar-policy-mcp-schema-generator-wasm makes a lot of sense. In that case, I don't think we need the TypeScript implementation anymore right?

[tomjwxf]

@lianah -- thank you! Agreed, the TypeScript reimplementation is no longer needed. I submitted the WASM bindings as #64 instead.

The WASM crate wraps the existing Rust SchemaGenerator via wasm-bindgen with zero independent logic. All type mapping, edge cases, and namespace handling is delegated to the Rust implementation. 3 tests passing, clippy clean with workspace lints, tested in Node.js.

Closing this PR in favor of #64.

Best,
Tom

[victornicolet]

Thank you! Closing this PR, I will review #64 .