Add an MCP tool to open Apollo Explorer (#32)

Author: pubmodmatt

Cargo.lock

@@ -10,6 +10,7 @@ apollo-compiler.workspace = true
 buildstructor = "0.6.0"
 clap = { version = "4.5.36", features = ["derive"] }
 derive-new = "0.7.0"
+lz-str = "0.2.1"
 mcp-apollo-registry = { path = "../mcp-apollo-registry" }
 reqwest = "0.12.15"
 rmcp = { version = "0.1", features = [
@@ -32,6 +33,8 @@ tokio = { version = "1.44.2", features = [
 tracing.workspace = true
 tracing-subscriber = { version = "0.3.19", features = ["env-filter"] }
 regex = "1.11.1"
+webbrowser = "1.0.4"
+base64 = "0.22.1"
 
 [dev-dependencies]
 insta = "1.42.2"

crates/mcp-apollo-server/Cargo.toml

@@ -0,0 +1,85 @@
+use crate::errors::McpError;
+use crate::schema_from_type;
+use base64::Engine;
+use rmcp::model::{CallToolResult, Content, ErrorCode, Tool};
+use rmcp::schemars::JsonSchema;
+use rmcp::serde_json::Value;
+use rmcp::{schemars, serde_json};
+use serde::Deserialize;
+
+pub(crate) const EXPLORER_TOOL_NAME: &str = "explorer";
+
+#[derive(Clone)]
+pub struct Explorer {
+    graph_id: String,
+    variant: String,
+    pub tool: Tool,
+}
+
+#[derive(JsonSchema, Deserialize)]
+#[allow(dead_code)] // This is only used to generate the JSON schema
+pub struct Input {
+    /// The GraphQL document
+    document: String,
+    variables: String,
+    headers: String,
+}
+
+impl Explorer {
+    pub fn new(graph_ref: String) -> Self {
+        let (graph_id, variant) = match graph_ref.split_once('@') {
+            Some((graph_id, variant)) => (graph_id.to_string(), variant.to_string()),
+            None => (graph_ref, String::from("current")),
+        };
+        Self {
+            graph_id,
+            variant,
+            tool: Tool::new(
+                EXPLORER_TOOL_NAME,
+                "Open a GraphQL operation in Apollo Explorer",
+                schema_from_type!(Input),
+            ),
+        }
+    }
+
+    fn create_explorer_url(&self, input: &Value) -> String {
+        let compressed = lz_str::compress_to_uint8_array(input.to_string().as_str());
+        let encoded = base64::engine::general_purpose::STANDARD.encode(compressed);
+        format!(
+            "https://studio.apollographql.com/graph/{graph_id}/variant/{variant}/explorer?explorerURLState={encoded}",
+            graph_id = self.graph_id,
+            variant = self.variant
+        )
+    }
+
+    pub async fn execute(&self, input: Value) -> Result<CallToolResult, McpError> {
+        webbrowser::open(self.create_explorer_url(&input).as_str())
+            .map(|_| CallToolResult {
+                content: vec![Content::text("success")],
+                is_error: None,
+            })
+            .map_err(|_| McpError::new(ErrorCode::INTERNAL_ERROR, "Unable to open browser", None))
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use rmcp::serde_json::json;
+
+    #[test]
+    fn test_create_explorer_url() {
+        let explorer = Explorer::new(String::from("mcp-example@mcp"));
+        let input = json!({
+            "document": "query GetWeatherAlerts($state: String!) {\n  alerts(state: $state) {\n    severity\n    description\n    instruction\n  }\n}",
+            "headers": "{}",
+            "variables": "{\"state\": \"CA\"}"
+        });
+
+        let url = explorer.create_explorer_url(&input);
+        assert_eq!(
+            url,
+            "https://studio.apollographql.com/graph/mcp-example/variant/mcp/explorer?explorerURLState=N4IgJg9gxgrgtgUwHYBcQC4QEcYIE4CeABAOIIoDqCAhigBb4CCANvigM4AUAJOyrQnREAyijwBLJAHMAhAEoiwADpIiRaqzwdOfAUN78UCBctVqi7BADd84lARXmiYBOygSADinEQkj85J8eDBQ3r7+AL4qESAANCAM1C547BggwDHxVtQS1ABGrKmYyiC6RkoYRBUAwowVMRFAAAA="
+        );
+    }
+}

crates/mcp-apollo-server/src/explorer.rs

@@ -2,6 +2,7 @@
 
 use crate::errors::McpError;
 use crate::graphql;
+use crate::schema_from_type;
 use apollo_compiler::Schema;
 use apollo_compiler::validation::Valid;
 use rmcp::model::{ErrorCode, Tool};
@@ -13,15 +14,6 @@ use serde::Deserialize;
 pub(crate) const GET_SCHEMA_TOOL_NAME: &str = "schema";
 pub(crate) const EXECUTE_TOOL_NAME: &str = "execute";
 
-macro_rules! schema_from_type {
-    ($type:ty) => {{
-        match serde_json::to_value(schemars::schema_for!($type)) {
-            Ok(Value::Object(schema)) => schema,
-            _ => panic!("Failed to generate schema for {}", stringify!($type)),
-        }
-    }};
-}
-
 #[derive(Clone)]
 pub struct GetSchema {
     pub schema: Valid<Schema>,

crates/mcp-apollo-server/src/introspection.rs

@@ -0,0 +1,10 @@
+/// Macro to generate a JSON schema from a type
+#[macro_export]
+macro_rules! schema_from_type {
+    ($type:ty) => {{
+        match serde_json::to_value(schemars::schema_for!($type)) {
+            Ok(Value::Object(schema)) => schema,
+            _ => panic!("Failed to generate schema for {}", stringify!($type)),
+        }
+    }};
+}

crates/mcp-apollo-server/src/json_schema.rs

@@ -1,7 +1,9 @@
 pub mod custom_scalar_map;
 pub mod errors;
+mod explorer;
 mod graphql;
 mod introspection;
+pub mod json_schema;
 pub mod operations;
 pub mod sanitize;
 pub mod server;

crates/mcp-apollo-server/src/lib.rs

@@ -54,10 +54,14 @@ struct Args {
     #[clap(long, short = 'i')]
     introspection: bool,
 
-    /// Enable use of uplink to get the schema and persisted queries
+    /// Enable use of uplink to get the schema and persisted queries (requires APOLLO_KEY and APOLLO_GRAPH_REF)
     #[clap(long, short = 'u')]
     uplink: bool,
 
+    /// Expose a tool to open queries in Apollo Explorer (requires APOLLO_KEY and APOLLO_GRAPH_REF)
+    #[clap(long, short = 'x')]
+    explorer: bool,
+
     /// Operation files to expose as MCP tools
     #[arg(long = "operations", short = 'o', num_args=0..)]
     operations: Vec<PathBuf>,
@@ -96,6 +100,7 @@ async fn main() -> anyhow::Result<()> {
         .headers(args.headers)
         .introspection(args.introspection)
         .uplink(args.uplink)
+        .explorer(args.explorer)
         .manifests(args.manifest.into_iter().collect())
         .and_custom_scalar_map(
             args.custom_scalars_config