pmcp_code_mode/
lib.rs

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

pmcp_code_mode/
lib.rs
