new plugin: serper web search

Signed-off-by: Tuan Anh Tran <[email protected]>

Author: tuananh

examples/plugins/serper/.cargo/config.toml

@@ -0,0 +1,2 @@
+[build]
+target = "wasm32-wasip1"

examples/plugins/serper/.gitignore

@@ -0,0 +1,21 @@
+# Generated by Cargo
+# will have compiled files and executables
+debug/
+target/
+
+# Remove Cargo.lock from gitignore if creating an executable, leave it for libraries
+# More information here https://doc.rust-lang.org/cargo/guide/cargo-toml-vs-cargo-lock.html
+Cargo.lock
+
+# These are backup files generated by rustfmt
+**/*.rs.bk
+
+# MSVC Windows builds of rustc generate these, which store debugging information
+*.pdb
+
+# RustRover
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/

examples/plugins/serper/Cargo.toml

@@ -0,0 +1,15 @@
+[package]
+name = "serper"
+version = "0.1.0"
+edition = "2024"
+
+[lib]
+name = "plugin"
+crate-type = ["cdylib"]
+
+[dependencies]
+extism-pdk = "=1.4.0"
+serde = { version = "1.0.219", features = ["derive"] }
+serde_json = "1.0.140"
+base64-serde = "0.8.0"
+base64 = "0.22.1"

examples/plugins/serper/Dockerfile

@@ -0,0 +1,14 @@
+FROM rust:1.86-slim AS builder
+
+RUN rustup target add wasm32-wasip1 && \
+    rustup component add rust-std --target wasm32-wasip1 && \
+    cargo install cargo-auditable
+
+WORKDIR /workspace
+COPY . .
+RUN cargo fetch
+RUN cargo auditable build --release --target wasm32-wasip1
+
+FROM scratch
+WORKDIR /
+COPY --from=builder /workspace/target/wasm32-wasip1/release/plugin.wasm /plugin.wasm

examples/plugins/serper/README.md

@@ -0,0 +1,27 @@
+# serper
+
+A plugin that performs Google web search using the [Serper](https://serper.dev) API and returns the raw JSON response for the given query string.
+
+## Requirements
+
+- Set `SERPER_API_KEY` in your config to your Serper API key.
+
+## Usage
+
+Call with:
+```json
+{
+  "plugins": [
+    {
+      "name": "serper",
+      "path": "oci://ghcr.io/tuananh/serper-plugin:latest",
+      "runtime_config": {
+        "env_var": {
+          "SERPER_API_KEY": "<your-serper-api-key>"
+        },
+        "allowed_hosts": ["google.serper.dev"] 
+      }
+    }
+  ]
+}
+```

examples/plugins/serper/src/lib.rs

@@ -0,0 +1,98 @@
+mod pdk;
+
+use std::collections::BTreeMap;
+
+use extism_pdk::*;
+use json::Value;
+use pdk::types::{
+    CallToolRequest, CallToolResult, Content, ContentType, ListToolsResult, ToolDescription,
+};
+use serde_json::json;
+
+pub(crate) fn call(input: CallToolRequest) -> Result<CallToolResult, Error> {
+    match input.params.name.as_str() {
+        "serper_web_search" => serper_web_search(input),
+        _ => Ok(CallToolResult {
+            is_error: Some(true),
+            content: vec![Content {
+                annotations: None,
+                text: Some(format!("Unknown tool: {}", input.params.name)),
+                mime_type: None,
+                r#type: ContentType::Text,
+                data: None,
+            }],
+        }),
+    }
+}
+
+fn serper_web_search(input: CallToolRequest) -> Result<CallToolResult, Error> {
+    let args = input.params.arguments.unwrap_or_default();
+    let query = match args.get("q") {
+        Some(Value::String(q)) => q.clone(),
+        _ => {
+            return Ok(CallToolResult {
+                is_error: Some(true),
+                content: vec![Content {
+                    annotations: None,
+                    text: Some("Please provide a 'q' argument for the search query".into()),
+                    mime_type: None,
+                    r#type: ContentType::Text,
+                    data: None,
+                }],
+            });
+        }
+    };
+
+    let api_key = config::get("SERPER_API_KEY")?
+        .ok_or_else(|| Error::msg("SERPER_API_KEY configuration is required but not set"))?;
+
+    let mut headers = BTreeMap::new();
+    headers.insert("X-API-KEY".to_string(), api_key);
+    headers.insert("Content-Type".to_string(), "application/json".to_string());
+
+    let req = HttpRequest {
+        url: "https://google.serper.dev/search".to_string(),
+        headers,
+        method: Some("POST".to_string()),
+    };
+
+    let body = json!({ "q": query });
+    let res = http::request(&req, Some(&body.to_string()))?;
+    let response_body = res.body();
+    let response_text = String::from_utf8_lossy(response_body.as_slice()).to_string();
+
+    Ok(CallToolResult {
+        is_error: None,
+        content: vec![Content {
+            annotations: None,
+            text: Some(response_text),
+            mime_type: Some("application/json".to_string()),
+            r#type: ContentType::Text,
+            data: None,
+        }],
+    })
+}
+
+pub(crate) fn describe() -> Result<ListToolsResult, Error> {
+    Ok(ListToolsResult{
+        tools: vec![
+            ToolDescription {
+                name: "serper_web_search".into(),
+                description:  "Performs a Google web search using the Serper API and returns the raw JSON response for the given query string.".into(),
+                input_schema: json!({
+                    "type": "object",
+                    "properties": {
+                        "q": {
+                            "type": "string",
+                            "description": "The search query string",
+                        },
+                    },
+                    "required": ["q"],
+                })
+                .as_object()
+                .unwrap()
+                .clone(),
+            },
+        ],
+    })
+}