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

pmcp_code_mode/
lib.rs
