From 5bea59540f58b3c45044828c10f131aed104dd1c Mon Sep 17 00:00:00 2001 From: Fahad Date: Mon, 6 Oct 2025 09:50:04 +0400 Subject: [PATCH] feat: new tool to perform apilookup (latest APIs / SDKs / language features etc) https://github.com/BeehiveInnovations/zen-mcp-server/issues/204 --- README.md | 2 + docs/tools/apilookup.md | 96 +++++++++++++++++++++++++++++++ server.py | 7 +++ tools/__init__.py | 2 + tools/apilookup.py | 122 ++++++++++++++++++++++++++++++++++++++++ 5 files changed, 229 insertions(+) create mode 100644 docs/tools/apilookup.md create mode 100644 tools/apilookup.py diff --git a/README.md b/README.md index 87d903e..6d33f20 100644 --- a/README.md +++ b/README.md @@ -220,6 +220,7 @@ Zen activates any provider that has credentials in your `.env`. See `.env.exampl - **[`docgen`](docs/tools/docgen.md)** - Generate documentation with complexity analysis **Utilities** +- **[`apilookup`](docs/tools/apilookup.md)** - Forces current-year API/SDK documentation lookups, prevents outdated training data responses - **[`challenge`](docs/tools/challenge.md)** - Prevent "You're absolutely right!" responses with critical analysis - **[`tracer`](docs/tools/tracer.md)** *(disabled by default - [enable](#tool-configuration))* - Static analysis prompts for call-flow mapping @@ -233,6 +234,7 @@ To optimize context window usage, only essential tools are enabled by default: **Enabled by default:** - `chat`, `thinkdeep`, `planner`, `consensus` - Core collaboration tools - `codereview`, `precommit`, `debug` - Essential code quality tools +- `apilookup` - Rapid API/SDK information lookup - `challenge` - Critical thinking utility **Disabled by default:** diff --git a/docs/tools/apilookup.md b/docs/tools/apilookup.md new file mode 100644 index 0000000..e37b944 --- /dev/null +++ b/docs/tools/apilookup.md @@ -0,0 +1,96 @@ +# API Lookup Tool + +The `apilookup` tool ensures you get **current, accurate API/SDK documentation** by forcing the AI to search for the latest information rather than relying on outdated training data. This is especially critical for OS-tied APIs (iOS, macOS, Android, etc.) where the AI's knowledge cutoff may be months or years old. + +## Why Use This Tool? + +### Without Zen (Using Standard AI) +``` +User: "How do I add glass look to a button in Swift?" + +AI: [Searches based on training data knowledge cutoff] + "SwiftUI glass morphism frosted glass effect button iOS 18 2025" + +Result: You get outdated APIs for iOS 18, which may not work with current iOS 19+ +``` + +### With Zen (Using apilookup) +``` +User: "use apilookup how do I add glass look to a button in swift?" + +AI: Step 1 - Search: "what is the latest iOS version 2025" + → Finds: iOS 19 is current + + Step 2 - Search: "iOS 19 SwiftUI glass effect button 2025" + → Gets current APIs specific to iOS 19 + +Result: You get the correct, current APIs that work with today's iOS version +``` + +## Key Features + +### 1. **OS Version Detection** (Critical!) +For any OS-tied request (iOS, macOS, Windows, Android, watchOS, tvOS), `apilookup` **MUST**: +- First search for the current OS version ("what is the latest iOS version 2025") +- **Never** rely on the AI's training data for version numbers +- Only after confirming current version, search for APIs/SDKs for that specific version + +### 2. **Authoritative Sources Only** +Prioritizes official documentation: +- Project documentation sites +- GitHub repositories +- Package registries (npm, PyPI, crates.io, Maven Central, etc.) +- Official blogs and release notes + +### 3. **Actionable, Concise Results** +- Current version numbers and release dates +- Breaking changes and migration notes +- Code examples and configuration options +- Deprecation warnings and security advisories + +## When to Use + +- You need current API/SDK documentation or version info +- You're working with OS-specific frameworks (SwiftUI, UIKit, Jetpack Compose, etc.) +- You want to verify which version supports a feature +- You need migration guides or breaking change notes +- You're checking for deprecations or security advisories + +## Usage Examples + +### OS-Specific APIs +``` +use apilookup how do I add glass look to a button in swift? +use apilookup what's the latest way to handle permissions in Android? +use apilookup how do I use the new macOS window management APIs? +``` + +### Library/Framework Versions +``` +use apilookup find the latest Stripe Python SDK version and note any breaking changes since v7 +use apilookup what's the current AWS CDK release and list migration steps from v2 +use apilookup check the latest React version and any new hooks introduced in 2025 +``` + +### Feature Compatibility +``` +use apilookup does the latest TypeScript support decorators natively? +use apilookup what's the current status of Swift async/await on Linux? +``` + +## How It Works + +1. **Receives your query** with API/SDK/framework name +2. **Injects mandatory instructions** that force current-year searches +3. **For OS-tied requests**: Requires two-step search (OS version first, then API) +4. **Returns structured guidance** with instructions for web search +5. **AI executes searches** and provides authoritative, current documentation + +## Output Format + +The tool returns JSON with: +- `status`: "web_lookup_needed" +- `instructions`: Detailed search strategy and requirements +- `user_prompt`: Your original request + +The AI then performs the actual web searches and synthesizes the results into actionable documentation. diff --git a/server.py b/server.py index 85c4434..f2cdf4e 100644 --- a/server.py +++ b/server.py @@ -49,6 +49,7 @@ from config import ( # noqa: E402 ) from tools import ( # noqa: E402 AnalyzeTool, + LookupTool, ChallengeTool, ChatTool, CLinkTool, @@ -272,6 +273,7 @@ TOOLS = { "tracer": TracerTool(), # Static call path prediction and control flow analysis "testgen": TestGenTool(), # Step-by-step test generation workflow with expert validation "challenge": ChallengeTool(), # Critical challenge prompt wrapper to avoid automatic agreement + "apilookup": LookupTool(), # Quick web/API lookup instructions "listmodels": ListModelsTool(), # List all available AI models by provider "version": VersionTool(), # Display server version and system information } @@ -354,6 +356,11 @@ PROMPT_TEMPLATES = { "description": "Challenge a statement critically without automatic agreement", "template": "Challenge this statement critically", }, + "apilookup": { + "name": "apilookup", + "description": "Look up the latest API or SDK information", + "template": "Lookup latest API docs for {model}", + }, "listmodels": { "name": "listmodels", "description": "List available AI models", diff --git a/tools/__init__.py b/tools/__init__.py index 1556a53..8bb17a9 100644 --- a/tools/__init__.py +++ b/tools/__init__.py @@ -3,6 +3,7 @@ Tool implementations for Zen MCP Server """ from .analyze import AnalyzeTool +from .apilookup import LookupTool from .challenge import ChallengeTool from .chat import ChatTool from .clink import CLinkTool @@ -26,6 +27,7 @@ __all__ = [ "DebugIssueTool", "DocgenTool", "AnalyzeTool", + "LookupTool", "ChatTool", "CLinkTool", "ConsensusTool", diff --git a/tools/apilookup.py b/tools/apilookup.py new file mode 100644 index 0000000..a52da65 --- /dev/null +++ b/tools/apilookup.py @@ -0,0 +1,122 @@ +"""API lookup tool - quickly gather the latest API/SDK information.""" + +from __future__ import annotations + +import json +from typing import TYPE_CHECKING, Any + +from pydantic import Field + +from config import TEMPERATURE_ANALYTICAL +from tools.shared.base_models import ToolRequest +from tools.simple.base import SimpleTool + +if TYPE_CHECKING: + from tools.models import ToolModelCategory + + +LOOKUP_FIELD_DESCRIPTIONS = { + "prompt": "The API, SDK, library, framework, or technology you need current documentation, version info, breaking changes, or migration guidance for.", +} + + +class LookupRequest(ToolRequest): + prompt: str = Field(..., description=LOOKUP_FIELD_DESCRIPTIONS["prompt"]) + + +LOOKUP_PROMPT = """ +MANDATORY: You MUST perform this research in a SEPARATE SUB-AGENT SUB-PROCESS using your web search tool. + +MISSION: +Research the latest, most authoritative documentation for the requested API, SDK, library, framework, programming language feature, or tool to answer the user's question accurately using a SUB-AGENT in a separate process. + +STRATEGY: +- IMPORTANT: Begin by determining today's date and current year +- MANDATORY FOR OS-TIED APIS/SDKs: If the request involves iOS, macOS, Windows, Linux, Android, watchOS, tvOS, or any OS-specific framework/API: + * FIRST perform a web search to determine "what is the latest [OS name] version [current year]" + * DO NOT rely on your training data or knowledge cutoff for OS versions - you MUST search for current information + * ONLY AFTER confirming the current OS version, search for APIs/SDKs/frameworks for that specific version + * Example workflow: Search "latest iOS version [current year]" → Find current version → Then search "[current iOS version] SwiftUI glass effect button [current year]" +- MANDATORY FOR MAJOR FRAMEWORKS/LANGUAGES: For rapidly-evolving ecosystems, verify current stable version: + * Languages: Node.js, Python, Ruby, Rust, Go, Java, .NET/C#, PHP, Kotlin, Swift + * Web frameworks: React, Vue, Angular, Next.js, Nuxt, Svelte, SvelteKit, Remix, Astro, SolidJS + * Backend frameworks: Django, Flask, FastAPI, Rails, Laravel, Spring Boot, Express, NestJS, Axum + * Mobile: Flutter, React Native, Jetpack Compose, SwiftUI + * Build tools: Vite, Webpack, esbuild, Turbopack, Rollup + * Package managers: npm, pnpm, yarn, pip, cargo, go modules, maven, gradle + * Search pattern: "latest [framework/language/SDK] version [current year]" BEFORE searching for specific APIs + * ONLY consider articles, documentation, and resources dated within the current year or most recent release cycle + * Ignore or deprioritize results from previous years unless they are still the current official documentation +- ALWAYS find current official documentation, release notes, changelogs, migration guides, and authoritative blog posts. Newest APIs / SDKs released or updated in the current year trump older ones. +- Prioritize official sources: project documentation sites, GitHub repositories, package registries (npm, PyPI, crates.io, Maven Central, NuGet, RubyGems, Packagist, etc.), and official blogs +- Check version-specific documentation when relevant and add current year to ensure latest docs are retrieved (e.g., "React docs [current year]", "Python what's new [current year]", "TypeScript breaking changes [current year]", "Next.js app router [current year]") +- Look for recent Stack Overflow discussions, GitHub issues, RFC documents, or official discussion forums when official docs are incomplete +- Cross-reference multiple sources to validate syntax, method signatures, configuration options, and best practices +- Search for deprecation warnings, security advisories, or migration paths between major versions +- If latest, more current, authoritative information has been found: STOP looking further +- ALWAYS cite authoritative sources with links (official docs, changelogs, GitHub releases, package registry pages) +""".strip() + + +class LookupTool(SimpleTool): + """Simple tool that wraps user queries with API lookup instructions.""" + + def get_name(self) -> str: + return "apilookup" + + def get_description(self) -> str: + return ( + "Use this tool automatically when you need current API/SDK documentation, latest version info, breaking changes, deprecations, migration guides, or official release notes. " + "This tool searches authoritative sources (official docs, GitHub, package registries) to ensure up-to-date accuracy." + ) + + def get_system_prompt(self) -> str: + return "" + + def get_default_temperature(self) -> float: + return TEMPERATURE_ANALYTICAL + + def requires_model(self) -> bool: + return False + + def get_model_category(self) -> "ToolModelCategory": + from tools.models import ToolModelCategory + + return ToolModelCategory.FAST_RESPONSE + + def get_request_model(self): + return LookupRequest + + def get_tool_fields(self) -> dict[str, dict[str, Any]]: + return { + "prompt": { + "type": "string", + "description": LOOKUP_FIELD_DESCRIPTIONS["prompt"], + } + } + + async def prepare_prompt(self, request) -> str: # pragma: no cover - not used + return "" + + def get_input_schema(self) -> dict[str, Any]: + return { + "type": "object", + "properties": { + "prompt": { + "type": "string", + "description": LOOKUP_FIELD_DESCRIPTIONS["prompt"], + }, + }, + "required": ["prompt"], + } + + async def execute(self, arguments: dict[str, Any]) -> list: + from mcp.types import TextContent + + request = self.get_request_model()(**arguments) + response = { + "status": "web_lookup_needed", + "instructions": LOOKUP_PROMPT, + "user_prompt": request.prompt, + } + return [TextContent(type="text", text=json.dumps(response, ensure_ascii=False, indent=2))]