pmcp_code_mode/
lib.rs

1//! Code Mode - LLM-generated query validation and execution.
2//!
3//! This crate provides the infrastructure for "Code Mode", which allows MCP clients
4//! to generate and execute structured queries (GraphQL, SQL, REST) with a validation
5//! pipeline that ensures security and provides human-readable explanations.
6//!
7//! ## Architecture
8//!
9//! ```text
10//! describe_schema() → LLM generates code → validate_code() → user approval → execute_code()
11//! ```
12//!
13//! ## Key Components
14//!
15//! - **Validation Pipeline**: Parse → Policy Check → Security Analysis → Explanation → Token
16//! - **Approval Tokens**: HMAC-signed tokens binding code hash to validation result
17//! - **Explanations**: Template-based business-language descriptions of queries
18//! - **Policy Evaluation**: Pluggable trait for Cedar/AVP/custom policy engines
19//!
20//! ## Example Usage
21//!
22//! ```ignore
23//! use pmcp_code_mode::{
24//!     CodeModeConfig, ValidationPipeline, ValidationContext
25//! };
26//!
27//! // Create a validation pipeline
28//! let config = CodeModeConfig::enabled();
29//! let pipeline = ValidationPipeline::new(config, b"secret-key".to_vec());
30//!
31//! // Validate a query
32//! let context = ValidationContext::new("user-123", "session-456", "schema-hash", "perms-hash");
33//! let result = pipeline.validate_graphql_query("query { users { id name } }", &context)?;
34//! ```
35
36pub mod config;
37mod explanation;
38mod graphql;
39pub mod handler;
40mod token;
41mod types;
42pub mod validation;
43
44// Code Mode instruction and policy templates
45pub mod templates;
46
47// Schema Exposure Architecture - Three-Layer Schema Model
48pub mod schema_exposure;
49
50// Policy evaluation framework
51pub mod policy;
52
53// Cedar policy annotation parsing (no AWS dependency)
54pub mod policy_annotations;
55
56// Cedar schema and policy validation (test only)
57#[cfg(test)]
58pub mod cedar_validation;
59
60// JavaScript validation for OpenAPI Code Mode (requires SWC parser)
61#[cfg(feature = "openapi-code-mode")]
62mod javascript;
63
64// JavaScript execution runtime (AST-based execution in pure Rust)
65#[cfg(feature = "js-runtime")]
66pub mod executor;
67
68// Shared expression evaluation logic (used by both sync and async executors)
69#[cfg(feature = "js-runtime")]
70mod eval;
71
72// Re-export public types
73pub use config::CodeModeConfig;
74
75pub use explanation::{ExplanationGenerator, TemplateExplanationGenerator};
76
77pub use graphql::{GraphQLOperationType, GraphQLQueryInfo, GraphQLValidator};
78
79// JavaScript/OpenAPI Code Mode exports
80#[cfg(feature = "openapi-code-mode")]
81pub use javascript::{
82    ApiCall, HttpMethod, JavaScriptCodeInfo, JavaScriptValidator, OutputDeclaration,
83    SafetyViolation, SafetyViolationType,
84};
85
86// JavaScript execution runtime exports
87#[cfg(feature = "js-runtime")]
88pub use executor::{
89    filter_blocked_fields,
90    find_blocked_fields_in_output,
91    ApiCallLog,
92    ArrayMethodCall,
93    BinaryOperator,
94    CompileError,
95    ExecutionConfig,
96    ExecutionPlan,
97    ExecutionResult,
98    HttpExecutor,
99    JsExecutor,
100    MockExecutionMode,
101    MockHttpExecutor,
102    MockedCall,
103    PathPart,
104    PathTemplate,
105    PlanCompiler,
106    PlanExecutor,
107    PlanMetadata,
108    PlanStep,
109    UnaryOperator,
110    ValueExpr,
111};
112
113// MCP Code Mode executor
114#[cfg(feature = "mcp-code-mode")]
115pub use executor::McpExecutor;
116
117pub use token::{
118    canonicalize_code, compute_context_hash, hash_code, ApprovalToken, HmacTokenGenerator,
119    TokenGenerator,
120};
121
122pub use types::{
123    CodeLocation, CodeType, Complexity, ExecutionError, PolicyViolation, RiskLevel,
124    SecurityAnalysis, SecurityIssue, SecurityIssueType, UnifiedAction, ValidationError,
125    ValidationMetadata, ValidationResult,
126};
127
128pub use validation::{ValidationContext, ValidationPipeline};
129
130// Code Mode templates
131pub use templates::TemplateContext;
132
133// Code Mode handler trait and utilities
134pub use handler::{
135    format_error_response, format_execution_error, CodeModeHandler, CodeModeToolBuilder,
136    ExecuteCodeInput, ValidateCodeInput, ValidationResponse,
137};
138
139// Policy types re-exports
140pub use policy::{
141    AuthorizationDecision, OperationEntity, PolicyEvaluationError, PolicyEvaluator,
142    ServerConfigEntity, get_baseline_policies, get_code_mode_schema_json,
143};
144
145#[cfg(feature = "openapi-code-mode")]
146pub use policy::{
147    OpenAPIServerEntity, ScriptEntity, get_openapi_baseline_policies,
148    get_openapi_code_mode_schema_json, normalize_operation_format, normalize_path_to_pattern,
149};
150
151// Cedar policy evaluator
152#[cfg(feature = "cedar")]
153pub use policy::cedar::CedarPolicyEvaluator;
154
155// Schema Exposure Architecture types
156pub use schema_exposure::{
157    CodeModeExposurePolicy,
158    DerivationMetadata,
159    DerivationStats,
160    DerivedSchema,
161    ExposureMode,
162    FilterReason,
163    FilteredOperation,
164    GlobalBlocklist,
165    McpExposurePolicy,
166    MethodExposurePolicy,
167    Operation,
168    OperationCategory,
169    OperationDetails,
170    OperationParameter,
171    OperationRiskLevel,
172    SchemaDeriver,
173    SchemaFormat,
174    SchemaMetadata,
175    SchemaSource,
176    ToolExposurePolicy,
177    ToolOverride,
178};
pmcp_code_mode/lib.rs

pmcp_code_mode/
lib.rs
