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// SQL validation for SQL Code Mode (requires sqlparser)
89#[cfg(feature = "sql-code-mode")]
90pub mod sql;
91
92// AWS Verified Permissions policy evaluator
93#[cfg(feature = "avp")]
94pub mod avp;
95
96// JavaScript execution runtime (AST-based execution in pure Rust)
97#[cfg(feature = "js-runtime")]
98pub mod executor;
99
100// Shared expression evaluation logic (used by both sync and async executors)
101#[cfg(feature = "js-runtime")]
102mod eval;
103
104// Re-export async_trait to avoid version conflicts in derive macro output (D-07)
105pub use async_trait::async_trait;
106
107// High-level CodeExecutor trait (always available, no feature gate) (D-04)
108pub use code_executor::CodeExecutor;
109
110// Re-export public types
111pub use config::{resolve_server_id_from_env, CodeModeConfig};
112
113pub use explanation::{ExplanationGenerator, TemplateExplanationGenerator};
114
115pub use graphql::{GraphQLOperationType, GraphQLQueryInfo, GraphQLValidator};
116
117// JavaScript/OpenAPI Code Mode exports
118#[cfg(feature = "openapi-code-mode")]
119pub use javascript::{
120    ApiCall, HttpMethod, JavaScriptCodeInfo, JavaScriptValidator, OutputDeclaration,
121    SafetyViolation, SafetyViolationType,
122};
123
124// SQL Code Mode exports
125#[cfg(feature = "sql-code-mode")]
126pub use sql::{SqlStatementInfo, SqlStatementType, SqlValidator};
127
128// JavaScript execution runtime exports
129#[cfg(feature = "js-runtime")]
130pub use executor::{
131    filter_blocked_fields, find_blocked_fields_in_output, ApiCallLog, ArrayMethodCall,
132    BinaryOperator, BuiltinFunction, CompileError, ExecutionConfig, ExecutionPlan, ExecutionResult,
133    HttpExecutor, JsExecutor, MockExecutionMode, MockHttpExecutor, MockedCall, PathPart,
134    PathTemplate, PlanCompiler, PlanExecutor, PlanMetadata, PlanStep, SdkExecutor, UnaryOperator,
135    ValueExpr,
136};
137
138// Standard CodeExecutor adapters (bridge low-level traits to derive-macro-compatible API)
139#[cfg(feature = "js-runtime")]
140pub use code_executor::{JsCodeExecutor, SdkCodeExecutor};
141
142// MCP Code Mode executor
143#[cfg(feature = "mcp-code-mode")]
144pub use executor::McpExecutor;
145
146#[cfg(feature = "mcp-code-mode")]
147pub use code_executor::McpCodeExecutor;
148
149pub use token::{
150    canonicalize_code, compute_context_hash, hash_code, ApprovalToken, HmacTokenGenerator,
151    TokenGenerator, TokenSecret,
152};
153
154pub use types::{
155    CodeLanguage, CodeLocation, CodeType, Complexity, ExecutionError, PolicyViolation, RiskLevel,
156    SecurityAnalysis, SecurityIssue, SecurityIssueType, TokenError, UnifiedAction, ValidationError,
157    ValidationMetadata, ValidationResult,
158};
159
160pub use validation::{ValidationContext, ValidationPipeline};
161
162// Code Mode templates
163pub use templates::TemplateContext;
164
165// Code Mode handler trait and utilities
166pub use handler::{
167    format_error_response, format_execution_error, CodeModeHandler, CodeModeToolBuilder,
168    ExecuteCodeInput, ValidateCodeInput, ValidationResponse,
169};
170
171// Policy types re-exports
172pub use policy::{
173    get_baseline_policies, get_code_mode_schema_json, AuthorizationDecision, NoopPolicyEvaluator,
174    OperationEntity, PolicyEvaluationError, PolicyEvaluator, ServerConfigEntity,
175};
176
177#[cfg(feature = "openapi-code-mode")]
178pub use policy::{
179    get_openapi_baseline_policies, get_openapi_code_mode_schema_json, normalize_operation_format,
180    normalize_path_to_pattern, OpenAPIServerEntity, ScriptEntity,
181};
182
183#[cfg(feature = "sql-code-mode")]
184pub use policy::{
185    get_sql_baseline_policies, get_sql_code_mode_schema_json, SqlServerEntity, StatementEntity,
186};
187
188// Cedar policy evaluator
189#[cfg(feature = "cedar")]
190pub use policy::cedar::CedarPolicyEvaluator;
191
192// AVP (AWS Verified Permissions) policy evaluator
193#[cfg(feature = "avp")]
194pub use avp::{AvpClient, AvpConfig, AvpError, AvpPolicyEvaluator};
195
196// Schema Exposure Architecture types
197pub use schema_exposure::{
198    CodeModeExposurePolicy, DerivationMetadata, DerivationStats, DerivedSchema, ExposureMode,
199    FilterReason, FilteredOperation, GlobalBlocklist, McpExposurePolicy, MethodExposurePolicy,
200    Operation, OperationCategory, OperationDetails, OperationParameter, OperationRiskLevel,
201    SchemaDeriver, SchemaFormat, SchemaMetadata, SchemaSource, ToolExposurePolicy, ToolOverride,
202};
pmcp_code_mode/lib.rs

pmcp_code_mode/
lib.rs
