@wentorai/research-plugins 1.3.2 → 1.4.2

package/src/tools/pubmed.ts

@@ -1,6 +1,6 @@
 import { Type } from "@sinclair/typebox";
 import type { OpenClawPluginApi, OpenClawPluginToolContext } from "openclaw/plugin-sdk";
-import { toolResult } from "./util.js";
+import { toolResult, trackedFetch, isTrackedError } from "./util.js";
 
 const EUTILS = "https://eutils.ncbi.nlm.nih.gov/entrez/eutils";
 
@@ -53,23 +53,27 @@ export function createPubMedTools(
         if (input.max_date) searchParams.set("maxdate", input.max_date);
         if (input.min_date || input.max_date) searchParams.set("datetype", "pdat");
 
-        const searchRes = await fetch(`${EUTILS}/esearch.fcgi?${searchParams}`);
-        if (!searchRes.ok)
-          return toolResult({ error: `Search error: ${searchRes.status} ${searchRes.statusText}` });
-        const searchData = await searchRes.json();
+        const searchTracked = await trackedFetch("pubmed", `${EUTILS}/esearch.fcgi?${searchParams}`);
+        if (isTrackedError(searchTracked)) return searchTracked;
+        const searchData = await searchTracked.res.json();
         const ids: string[] = searchData.esearchresult?.idlist ?? [];
 
-        if (ids.length === 0) return toolResult({ total_count: searchData.esearchresult?.count ?? 0, articles: [] });
+        if (ids.length === 0) {
+          return toolResult({
+            total_count: searchData.esearchresult?.count ?? 0,
+            articles: [],
+            _source_health: { source: "pubmed", latency_ms: searchTracked.latency_ms },
+          });
+        }
 
         const summaryParams = new URLSearchParams({
           db: "pubmed",
           id: ids.join(","),
           retmode: "json",
         });
-        const summaryRes = await fetch(`${EUTILS}/esummary.fcgi?${summaryParams}`);
-        if (!summaryRes.ok)
-          return toolResult({ error: `Summary error: ${summaryRes.status} ${summaryRes.statusText}` });
-        const summaryData = await summaryRes.json();
+        const summaryTracked = await trackedFetch("pubmed", `${EUTILS}/esummary.fcgi?${summaryParams}`);
+        if (isTrackedError(summaryTracked)) return summaryTracked;
+        const summaryData = await summaryTracked.res.json();
 
         const articles = ids.map((id) => {
           const doc = summaryData.result?.[id];
@@ -92,6 +96,7 @@ export function createPubMedTools(
         return toolResult({
           total_count: parseInt(searchData.esearchresult?.count ?? "0", 10),
           articles,
+          _source_health: { source: "pubmed", latency_ms: summaryTracked.latency_ms },
         });
       },
     },
@@ -104,14 +109,17 @@ export function createPubMedTools(
         pmid: Type.String({ description: "PubMed ID (numeric string)" }),
       }),
       execute: async (input: { pmid: string }) => {
+        if (!input?.pmid) {
+          return toolResult({ error: 'pmid parameter is required (numeric PubMed ID, e.g., "33116299")' });
+        }
         const params = new URLSearchParams({
           db: "pubmed",
           id: input.pmid,
           retmode: "xml",
         });
-        const res = await fetch(`${EUTILS}/efetch.fcgi?${params}`);
-        if (!res.ok) return toolResult({ error: `API error: ${res.status} ${res.statusText}` });
-        const xml = await res.text();
+        const tracked = await trackedFetch("pubmed", `${EUTILS}/efetch.fcgi?${params}`);
+        if (isTrackedError(tracked)) return tracked;
+        const xml = await tracked.res.text();
 
         const getText = (tag: string) => {
           const m = xml.match(new RegExp(`<${tag}>([\\s\\S]*?)</${tag}>`));
@@ -162,6 +170,7 @@ export function createPubMedTools(
           pmc,
           mesh_terms: getMesh(),
           url: `https://pubmed.ncbi.nlm.nih.gov/${input.pmid}/`,
+          _source_health: { source: "pubmed", latency_ms: tracked.latency_ms },
         });
       },
     },

package/src/tools/ror.ts

@@ -0,0 +1,118 @@
+import { Type } from "@sinclair/typebox";
+import type { OpenClawPluginApi, OpenClawPluginToolContext } from "openclaw/plugin-sdk";
+import { toolResult, trackedFetch, isTrackedError } from "./util.js";
+
+const BASE = "https://api.ror.org/v2";
+
+export function createRorTools(
+  _ctx: OpenClawPluginToolContext,
+  _api: OpenClawPluginApi,
+) {
+  return [
+    {
+      name: "search_ror",
+      label: "Search Research Organizations (ROR)",
+      description:
+        "Search the Research Organization Registry (ROR) for institutions, universities, labs, and funders. Returns canonical identifiers, locations, types, and links. Useful for affiliation disambiguation and finding institution metadata.",
+      parameters: Type.Object({
+        query: Type.String({
+          description: "Organization name or acronym to search, e.g. 'MIT', 'Max Planck', 'CNRS'",
+        }),
+        max_results: Type.Optional(
+          Type.Number({ description: "Max results (default 10, max 50)" }),
+        ),
+      }),
+      execute: async (input: { query: string; max_results?: number }) => {
+        const params = new URLSearchParams({
+          query: input.query,
+        });
+
+        const tracked = await trackedFetch("ror", `${BASE}/organizations?${params}`, undefined, 10_000);
+        if (isTrackedError(tracked)) return tracked;
+        const data = await tracked.res.json();
+
+        const maxResults = Math.min(input.max_results ?? 10, 50);
+        const items = (data.items ?? []).slice(0, maxResults).map(
+          (org: Record<string, unknown>) => {
+            const names = org.names as Array<{
+              value: string;
+              types: string[];
+              lang: string | null;
+            }> | undefined;
+            const locations = org.locations as Array<{
+              geonames_details: {
+                name: string;
+                country_name: string;
+                country_code: string;
+                country_subdivision_name?: string;
+                lat: number;
+                lng: number;
+              };
+            }> | undefined;
+            const links = org.links as Array<{
+              type: string;
+              value: string;
+            }> | undefined;
+            const externalIds = org.external_ids as Array<{
+              type: string;
+              all: string[];
+              preferred: string | null;
+            }> | undefined;
+
+            // Extract the display name (ror_display type preferred, then first label)
+            const displayName = names?.find(
+              (n) => n.types.includes("ror_display"),
+            )?.value;
+            const acronym = names?.find(
+              (n) => n.types.includes("acronym"),
+            )?.value;
+            const aliases = names
+              ?.filter((n) => n.types.includes("alias"))
+              .map((n) => n.value);
+            const labels = names
+              ?.filter((n) => n.types.includes("label") && !n.types.includes("ror_display"))
+              .map((n) => ({ name: n.value, lang: n.lang }));
+
+            const location = locations?.[0]?.geonames_details;
+            const website = links?.find((l) => l.type === "website")?.value;
+            const wikipedia = links?.find((l) => l.type === "wikipedia")?.value;
+
+            // Extract GRID and other IDs
+            const gridId = externalIds?.find((e) => e.type === "grid")?.preferred;
+            const wikidataId = externalIds?.find((e) => e.type === "wikidata")?.preferred;
+
+            return {
+              ror_id: org.id,
+              name: displayName ?? names?.[0]?.value,
+              acronym,
+              aliases: aliases?.length ? aliases : undefined,
+              labels: labels?.length ? labels : undefined,
+              types: org.types,
+              status: org.status,
+              established: org.established,
+              location: location
+                ? {
+                    city: location.name,
+                    country: location.country_name,
+                    country_code: location.country_code,
+                    region: location.country_subdivision_name,
+                  }
+                : undefined,
+              website,
+              wikipedia,
+              domains: org.domains,
+              grid_id: gridId,
+              wikidata_id: wikidataId,
+            };
+          },
+        );
+
+        return toolResult({
+          total_results: data.number_of_results,
+          organizations: items,
+          _source_health: { source: "ror", latency_ms: tracked.latency_ms },
+        });
+      },
+    },
+  ];
+}

package/src/tools/unpaywall.ts

@@ -1,6 +1,6 @@
 import { Type } from "@sinclair/typebox";
 import type { OpenClawPluginApi, OpenClawPluginToolContext } from "openclaw/plugin-sdk";
-import { toolResult } from "./util.js";
+import { toolResult, trackedFetch, isTrackedError } from "./util.js";
 
 const BASE = "https://api.unpaywall.org/v2";
 
@@ -22,15 +22,23 @@ export function createUnpaywallTools(
         }),
       }),
       execute: async (input: { doi: string }) => {
+        if (!input?.doi) {
+          return toolResult({ error: 'doi parameter is required (e.g., "10.1038/nature12373")' });
+        }
         const doi = input.doi.replace(/^https?:\/\/doi\.org\//, "");
-        const res = await fetch(
+        const tracked = await trackedFetch(
+          "unpaywall",
           `${BASE}/${encodeURIComponent(doi)}?email=${email}`,
         );
-        if (!res.ok) {
-          if (res.status === 404) return toolResult({ error: "DOI not found in Unpaywall" });
-          return toolResult({ error: `API error: ${res.status} ${res.statusText}` });
+        if (isTrackedError(tracked)) {
+          // Special handling for 404 (DOI not found)
+          if (tracked.details && typeof tracked.details === "object" && "error" in (tracked.details as Record<string, unknown>)) {
+            const errMsg = String((tracked.details as Record<string, string>).error);
+            if (errMsg.includes("404")) return toolResult({ error: "DOI not found in Unpaywall" });
+          }
+          return tracked;
         }
-        const data = await res.json();
+        const data = await tracked.res.json();
 
         const oaLocations = (
           data.oa_locations as Record<string, unknown>[] | undefined
@@ -53,6 +61,7 @@ export function createUnpaywallTools(
           publisher: data.publisher,
           published_date: data.published_date,
           oa_locations: oaLocations,
+          _source_health: { source: "unpaywall", latency_ms: tracked.latency_ms },
         });
       },
     },

package/src/tools/util.ts

@@ -9,3 +9,144 @@ export function toolResult(data: unknown) {
   const text = JSON.stringify(data, null, 2);
   return { content: [{ type: "text" as const, text }], details: data };
 }
+
+// ── Source Health Tracking ───────────────────────────────────────────────
+
+interface SourceHealthEntry {
+  source: string;
+  total_calls: number;
+  successes: number;
+  failures: number;
+  last_status: number | null;
+  last_latency_ms: number | null;
+  last_error: string | null;
+  avg_latency_ms: number;
+  last_called: string | null;
+}
+
+const healthRegistry = new Map<string, SourceHealthEntry>();
+
+function getOrCreateEntry(source: string): SourceHealthEntry {
+  let entry = healthRegistry.get(source);
+  if (!entry) {
+    entry = {
+      source,
+      total_calls: 0,
+      successes: 0,
+      failures: 0,
+      last_status: null,
+      last_latency_ms: null,
+      last_error: null,
+      avg_latency_ms: 0,
+      last_called: null,
+    };
+    healthRegistry.set(source, entry);
+  }
+  return entry;
+}
+
+function recordSuccess(entry: SourceHealthEntry, status: number, latencyMs: number) {
+  entry.total_calls++;
+  entry.successes++;
+  entry.last_status = status;
+  entry.last_latency_ms = latencyMs;
+  entry.last_error = null;
+  entry.last_called = new Date().toISOString();
+  entry.avg_latency_ms = Math.round(
+    (entry.avg_latency_ms * (entry.total_calls - 1) + latencyMs) / entry.total_calls,
+  );
+}
+
+function recordFailure(entry: SourceHealthEntry, error: string, status?: number) {
+  entry.total_calls++;
+  entry.failures++;
+  entry.last_status = status ?? null;
+  entry.last_error = error;
+  entry.last_called = new Date().toISOString();
+}
+
+export interface TrackedResponse {
+  res: Response;
+  latency_ms: number;
+  source: string;
+}
+
+/**
+ * Fetch with automatic source health tracking, timeout, and error handling.
+ *
+ * @param source - Source identifier (e.g. "europe_pmc", "dblp")
+ * @param url - Request URL
+ * @param options - Fetch options
+ * @param timeoutMs - Timeout in milliseconds (default: 10000)
+ * @returns TrackedResponse on success, or a toolResult error on failure
+ */
+export async function trackedFetch(
+  source: string,
+  url: string,
+  options?: RequestInit,
+  timeoutMs = 10_000,
+): Promise<TrackedResponse | ReturnType<typeof toolResult>> {
+  const entry = getOrCreateEntry(source);
+  const start = Date.now();
+
+  try {
+    const res = await fetch(url, {
+      ...options,
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+    const latency = Date.now() - start;
+
+    if (!res.ok) {
+      recordFailure(entry, `HTTP ${res.status} ${res.statusText}`, res.status);
+      return toolResult({
+        error: `${source} API error: ${res.status} ${res.statusText}`,
+        _source_health: {
+          source,
+          status: res.status,
+          latency_ms: latency,
+          success_rate: entry.total_calls > 0
+            ? `${Math.round((entry.successes / entry.total_calls) * 100)}%`
+            : "N/A",
+        },
+      });
+    }
+
+    recordSuccess(entry, res.status, latency);
+    return { res, latency_ms: latency, source };
+  } catch (err) {
+    const latency = Date.now() - start;
+    const message = err instanceof Error ? err.message : String(err);
+    const isTimeout = message.includes("abort") || message.includes("timeout");
+    recordFailure(entry, isTimeout ? `Timeout after ${timeoutMs}ms` : message);
+
+    return toolResult({
+      error: `${source} ${isTimeout ? "timeout" : "network error"}: ${message}`,
+      _source_health: {
+        source,
+        latency_ms: latency,
+        success_rate: entry.total_calls > 0
+          ? `${Math.round((entry.successes / entry.total_calls) * 100)}%`
+          : "N/A",
+        suggestion: isTimeout
+          ? "This source is slow. Try a different source or reduce result count."
+          : "This source may be temporarily unavailable. Try an alternative.",
+      },
+    });
+  }
+}
+
+/**
+ * Get health status for all tracked sources. Useful for agent decision-making.
+ */
+export function getSourceHealth(): SourceHealthEntry[] {
+  return Array.from(healthRegistry.values());
+}
+
+/**
+ * Check if a tracked fetch result is an error (toolResult) or success (TrackedResponse).
+ */
+export function isTrackedError(
+  result: TrackedResponse | ReturnType<typeof toolResult>,
+): result is ReturnType<typeof toolResult> {
+  return "content" in result && "details" in result;
+}

package/src/tools/zenodo.ts

@@ -0,0 +1,157 @@
+import { Type } from "@sinclair/typebox";
+import type { OpenClawPluginApi, OpenClawPluginToolContext } from "openclaw/plugin-sdk";
+import { toolResult, trackedFetch, isTrackedError } from "./util.js";
+
+const BASE = "https://zenodo.org/api";
+
+export function createZenodoTools(
+  _ctx: OpenClawPluginToolContext,
+  _api: OpenClawPluginApi,
+) {
+  return [
+    {
+      name: "search_zenodo",
+      label: "Search Records (Zenodo)",
+      description:
+        "Search Zenodo for open research data, software, publications, and other research outputs. Covers 3M+ records with DOIs. Uniquely includes datasets, software, presentations, and other non-publication outputs.",
+      parameters: Type.Object({
+        query: Type.String({ description: "Search query" }),
+        type: Type.Optional(
+          Type.String({
+            description:
+              "Resource type filter: 'publication', 'dataset', 'software', 'image', 'video', 'lesson', 'poster', 'presentation'",
+          }),
+        ),
+        size: Type.Optional(
+          Type.Number({ description: "Max results (default 10, max 100)" }),
+        ),
+        sort: Type.Optional(
+          Type.String({
+            description:
+              "Sort by: 'bestmatch' (relevance), 'mostrecent', '-mostrecent' (oldest first)",
+          }),
+        ),
+        access_right: Type.Optional(
+          Type.String({
+            description: "Access filter: 'open', 'embargoed', 'restricted', 'closed'",
+          }),
+        ),
+      }),
+      execute: async (input: {
+        query: string;
+        type?: string;
+        size?: number;
+        sort?: string;
+        access_right?: string;
+      }) => {
+        const params = new URLSearchParams({
+          q: input.query,
+          size: String(Math.min(input.size ?? 10, 100)),
+        });
+        if (input.type) params.set("type", input.type);
+        if (input.sort) params.set("sort", input.sort);
+        if (input.access_right) params.set("access_right", input.access_right);
+
+        const result = await trackedFetch("zenodo", `${BASE}/records?${params}`, undefined, 10_000);
+        if (isTrackedError(result)) return result;
+        const data = await result.res.json();
+
+        return toolResult({
+          total_results: data.hits?.total,
+          source: "zenodo",
+          records: data.hits?.hits?.map(
+            (h: Record<string, unknown>) => {
+              const meta = h.metadata as Record<string, unknown> | undefined;
+              const creators = meta?.creators as Array<{ name: string; affiliation?: string }> | undefined;
+              const resourceType = meta?.resource_type as Record<string, string> | undefined;
+              const license = meta?.license as Record<string, string> | undefined;
+
+              return {
+                id: h.id,
+                doi: meta?.doi ?? h.doi,
+                title: meta?.title ?? h.title,
+                authors: creators?.map((c) => c.name),
+                year: meta?.publication_date
+                  ? String(meta.publication_date).slice(0, 4)
+                  : undefined,
+                publication_date: meta?.publication_date,
+                resource_type: resourceType?.type,
+                access_right: meta?.access_right,
+                keywords: meta?.keywords,
+                license: license?.id,
+                description: meta?.description
+                  ? String(meta.description).replace(/<[^>]*>/g, "").slice(0, 300)
+                  : undefined,
+                url: (h.links as Record<string, string>)?.self_html
+                  ?? `https://zenodo.org/records/${h.id}`,
+                source: "zenodo",
+              };
+            },
+          ),
+          _latency_ms: result.latency_ms,
+        });
+      },
+    },
+    {
+      name: "get_zenodo_record",
+      label: "Get Record Details (Zenodo)",
+      description:
+        "Get full details of a specific Zenodo record by its numeric ID. Returns metadata, files, and download links.",
+      parameters: Type.Object({
+        record_id: Type.String({
+          description: "Zenodo record ID (numeric), e.g. '7042164'",
+        }),
+      }),
+      execute: async (input: { record_id: string }) => {
+        if (!input?.record_id) {
+          return toolResult({ error: 'record_id parameter is required (e.g., "1234567")' });
+        }
+        const id = input.record_id.replace(/\D/g, "");
+        const result = await trackedFetch("zenodo", `${BASE}/records/${id}`, undefined, 10_000);
+        if (isTrackedError(result)) return result;
+        const h = await result.res.json();
+
+        const meta = h.metadata as Record<string, unknown> | undefined;
+        const creators = meta?.creators as Array<{ name: string; affiliation?: string }> | undefined;
+        const resourceType = meta?.resource_type as Record<string, string> | undefined;
+        const license = meta?.license as Record<string, string> | undefined;
+        const files = h.files as Array<{ key: string; size: number; links?: Record<string, string> }> | undefined;
+        const stats = h.stats as Record<string, number> | undefined;
+
+        return toolResult({
+          id: h.id,
+          doi: meta?.doi ?? h.doi,
+          title: meta?.title ?? h.title,
+          authors: creators?.map((c) => c.name),
+          year: meta?.publication_date
+            ? String(meta.publication_date).slice(0, 4)
+            : undefined,
+          publication_date: meta?.publication_date,
+          description: meta?.description
+            ? String(meta.description).replace(/<[^>]*>/g, "")
+            : undefined,
+          resource_type: resourceType?.type,
+          access_right: meta?.access_right,
+          keywords: meta?.keywords,
+          license: license?.id,
+          version: meta?.version,
+          files: files?.map((f) => ({
+            filename: f.key,
+            size_bytes: f.size,
+            download_url: f.links?.self,
+          })),
+          stats: stats
+            ? {
+                downloads: stats.downloads,
+                views: stats.views,
+              }
+            : undefined,
+          url: (h.links as Record<string, string>)?.self_html
+            ?? `https://zenodo.org/records/${h.id}`,
+          source: "zenodo",
+          _latency_ms: result.latency_ms,
+        });
+      },
+    },
+  ];
+}

package/mcp-configs/academic-db/ChatSpatial.json

@@ -1,17 +0,0 @@
-{
-  "id": "ChatSpatial",
-  "name": "ChatSpatial",
-  "description": "Spatial transcriptomics analysis via natural language",
-  "category": "academic-db",
-  "install": {
-    "runtime": "python",
-    "package": "ChatSpatial",
-    "command": "pip install ChatSpatial"
-  },
-  "config": {
-    "env": {}
-  },
-  "tools": ["load_data", "identify_domains", "visualize"],
-  "verified": false,
-  "source": "https://github.com/cafferychen777/ChatSpatial"
-}

package/mcp-configs/academic-db/academia-mcp.json

@@ -1,17 +0,0 @@
-{
-  "id": "academia-mcp",
-  "name": "Academia MCP",
-  "description": "Tools for automatic scientific research",
-  "category": "academic-db",
-  "install": {
-    "runtime": "python",
-    "package": "academia-mcp",
-    "command": "pip install academia-mcp"
-  },
-  "config": {
-    "env": {}
-  },
-  "tools": ["search", "analyze"],
-  "verified": false,
-  "source": "https://github.com/IlyaGusev/academia_mcp"
-}

package/mcp-configs/academic-db/academic-paper-explorer.json

@@ -1,17 +0,0 @@
-{
-  "id": "academic-paper-explorer",
-  "name": "Academic Paper Explorer",
-  "description": "Academic paper discovery via arXiv and Semantic Scholar",
-  "category": "academic-db",
-  "install": {
-    "runtime": "node",
-    "package": "academic-paper-explorer",
-    "command": "npm install -g academic-paper-explorer"
-  },
-  "config": {
-    "env": {}
-  },
-  "tools": ["search", "read_paper", "find_code"],
-  "verified": false,
-  "source": "https://github.com/Leonard013/academic-paper-explorer"
-}

package/mcp-configs/academic-db/academic-search-mcp-server.json

@@ -1,17 +0,0 @@
-{
-  "id": "academic-search-mcp-server",
-  "name": "Academic Paper Search",
-  "description": "Academic Paper Search MCP for Semantic Scholar and Crossref APIs",
-  "category": "academic-db",
-  "install": {
-    "runtime": "python",
-    "package": "academic-search-mcp-server",
-    "command": "pip install academic-search-mcp-server"
-  },
-  "config": {
-    "env": {}
-  },
-  "tools": ["search_papers", "fetch_paper_details", "search_by_topic"],
-  "verified": false,
-  "source": "https://github.com/afrise/academic-search-mcp-server"
-}

package/mcp-configs/academic-db/agentinterviews-mcp.json

@@ -1,17 +0,0 @@
-{
-  "id": "agentinterviews-mcp",
-  "name": "Agent Interviews",
-  "description": "AI-powered qualitative research interviews at scale",
-  "category": "academic-db",
-  "install": {
-    "runtime": "python",
-    "package": "agentinterviews-mcp",
-    "command": "pip install agentinterviews-mcp"
-  },
-  "config": {
-    "env": {}
-  },
-  "tools": ["create_interviewer", "manage_project", "analyze_data"],
-  "verified": false,
-  "source": "https://github.com/thinkchainai/agentinterviews_mcp"
-}

package/mcp-configs/academic-db/all-in-mcp.json

@@ -1,17 +0,0 @@
-{
-  "id": "all-in-mcp",
-  "name": "All-in MCP",
-  "description": "Academic paper search and PDF processing",
-  "category": "academic-db",
-  "install": {
-    "runtime": "python",
-    "package": "all-in-mcp",
-    "command": "pip install all-in-mcp"
-  },
-  "config": {
-    "env": {}
-  },
-  "tools": ["search", "process_pdf"],
-  "verified": false,
-  "source": "https://github.com/isomoes/all-in-mcp"
-}

package/mcp-configs/academic-db/alphafold-mcp.json

@@ -1,20 +0,0 @@
-{
-  "id": "alphafold-mcp",
-  "name": "AlphaFold MCP",
-  "description": "AlphaFold Protein Structure Database for structure prediction",
-  "category": "academic-db",
-  "install": {
-    "runtime": "node",
-    "package": "alphafold-mcp-server",
-    "command": "npm install -g alphafold-mcp-server"
-  },
-  "config": {
-    "env": {}
-  },
-  "tools": [
-    "get_structure",
-    "search_protein"
-  ],
-  "verified": false,
-  "source": "https://github.com/ac3xx/AlphaFold-MCP-Server"
-}