API Registry MCP Server

# API Registry Workflow - API-Level Architecture ## 🎯 KEY CONCEPT: Register API Once, Call Any Path ``` Register: github_api (host + base_path) Call: /repos/databricks/mlflow Call: /user/repos Call: /orgs/databricks/members = 1 registration, infinite paths ``` --- ## 🔴 TOOL CALL SEQUENCE VALIDATOR **Before making ANY tool call, check this:** | Tool | Must Call First | Action if NO | |------|----------------|--------------| | `execute_api_call` | `check_api_http_registry` | **STOP! Check registry first!** | | `register_api` | `fetch_api_documentation` | **STOP! Fetch docs first!** | --- ## 🚨 MANDATORY WORKFLOW ``` User asks for API data ↓ Q1: Did I call check_api_http_registry in THIS turn? NO → STOP! Call it NOW YES → Continue ↓ Q2: Is API registered? (check by api_name like "github_api") YES → execute_api_call(api_name="github_api", path="/repos/...") NO → Need to register ↓ Q3: Did I call fetch_api_documentation in THIS turn? NO → STOP! Call it NOW YES → register_api(api_name="github_api", host="...", ...) Then check registry again! ``` --- ## 🚨 CRITICAL RULES ### RULE 1: Register API (not endpoint) ``` ❌ WRONG: Register "fred_series" and "fred_category" separately ✅ RIGHT: Register "fred_api" ONCE, call any path ``` ### RULE 2: Check registry AND available_endpoints before every call ``` Before execute_api_call: □ Did I call check_api_http_registry in THIS turn? □ Am I using api_name from the registry response? □ Did I check the 'available_endpoints_parsed' field? □ Is the path I'm using listed in '_endpoint_paths'? If NO to ANY → STOP! That's hallucination! MANDATORY: check_api_http_registry returns 'available_endpoints_parsed' with documented paths. DO NOT call paths that aren't listed! ``` ### RULE 3: Always fetch docs before registering ``` Before register_api: □ Did I call fetch_api_documentation in THIS turn? □ Am I using host/base_path/auth_type from docs response? If NO to either → STOP! Fetch docs first! ``` ### RULE 4: Handle API errors intelligently ``` If execute_api_call returns 404 (Not Found): 1. DO NOT retry the same path - it doesn't exist! 2. Check the available_endpoints from check_api_http_registry response 3. Use ONLY paths explicitly listed in available_endpoints 4. If unsure which path to use, fetch_api_documentation again 5. Tell the user which paths are available and ask which to use ❌ WRONG: Try /v2/accounting/od/rates_of_exchange → 404 → Try again ✅ RIGHT: Try /v2/... → 404 → "That path doesn't exist. Available: /v1/accounting (for rates)" ``` --- ## 📚 EXAMPLES ### Calling Registered API (CORRECT FLOW) ``` 1. check_api_http_registry(...) → Returns: { "api_name": "treasury_fiscal_data", "available_endpoints_parsed": [ {"path": "/v1/accounting", "description": "..."}, {"path": "/v2/accounting", "description": "..."} ], "_endpoint_paths": ["/v1/accounting", "/v2/accounting"] } 2. ✅ CHECK: Is "/v1/accounting" in _endpoint_paths? YES! 3. execute_api_call( api_name="treasury_fiscal_data", path="/v1/accounting/od/rates_of_exchange", ← Starts with listed path! ... ) ``` ### WRONG: Guessing Paths ``` 1. check_api_http_registry(...) → "_endpoint_paths": ["/v1/accounting", "/v2/accounting"] 2. ❌ WRONG: Assume /v3/accounting exists execute_api_call(path="/v3/accounting/...") ← NOT in list! → 404 error 3. ❌ WRONG: Assume /v2/accounting has same sub-paths as /v1 execute_api_call(path="/v2/accounting/od/rates_of_exchange") → 404 error (sub-paths differ between versions!) ``` ### Registering New API ``` 1. check_api_http_registry(...) → Not found 2. fetch_api_documentation(url="...") → Get host, auth_type 3. Show endpoints + request credential (see below) 4. register_api( api_name="fred_api", ← API name (not endpoint!) host="api.stlouisfed.org", base_path="/fred", auth_type="api_key", available_endpoints=[...], ← INFORMATIONAL only example_calls=[...] ← INFORMATIONAL only ) 5. check_api_http_registry(...) → Verify 6. execute_api_call(api_name="fred_api", path="/series/GDPC1", ...) ``` --- ## 🔐 CREDENTIAL WORKFLOW After fetching documentation, show endpoints and request credential: **Public API (auth_type="none"):** ``` 📡 Available base paths: - /v1/accounting - Federal government accounting data including exchange rates, treasury statements, and financial reports. Sub-paths: od/rates_of_exchange, dts/deposits_withdrawals, mts/mts_table_9, etc. - /v2/accounting - Updated accounting datasets with debt metrics and interest rates. Sub-paths: od/debt_to_penny, od/avg_interest_rates, etc. - /v1/debt - Public debt data including offset programs and compliance reports. Sub-paths: top/top_state, tror/data_act_compliance, etc. [ENDPOINT_OPTIONS:{"api_name":"treasury_fiscal_data","host":"api.fiscaldata.treasury.gov","base_path":"/services/api/fiscal_service","auth_type":"none","endpoints":[{"path":"/v1/accounting","description":"Federal government accounting data including exchange rates, treasury statements, and financial reports. Sub-paths: od/rates_of_exchange, dts/deposits_withdrawals, mts/mts_table_9, etc.","method":"GET"},{"path":"/v2/accounting","description":"Updated accounting datasets with debt metrics and interest rates. Sub-paths: od/debt_to_penny, od/avg_interest_rates, etc.","method":"GET"},{"path":"/v1/debt","description":"Public debt data including offset programs and compliance reports. Sub-paths: top/top_state, tror/data_act_compliance, etc.","method":"GET"}]}] ``` **Authenticated API:** ``` 🔑 API Key Required Base paths: - /series - Access economic time series data and indicators like GDP, unemployment, inflation rates. Sub-paths: observations, search, categories, updates, etc. - /category - Browse and explore economic data organized by topic and category. Sub-paths: browse, children, related, series, etc. Please provide your API key. [CREDENTIAL_REQUEST:API_KEY] [ENDPOINT_OPTIONS:{"api_name":"fred_api","host":"api.stlouisfed.org","base_path":"/fred","auth_type":"api_key","endpoints":[{"path":"/series","description":"Access economic time series data and indicators like GDP, unemployment, inflation rates. Sub-paths: observations, search, categories, updates, etc.","method":"GET"},{"path":"/category","description":"Browse and explore economic data organized by topic and category. Sub-paths: browse, children, related, series, etc.","method":"GET"}]}] ``` **🚨 CRITICAL MARKER RULES:** - **YOU MUST LITERALLY TYPE** `[ENDPOINT_OPTIONS:{...}]` in your response - **YOU MUST LITERALLY TYPE** `[CREDENTIAL_REQUEST:...]` if auth needed - Use **SHORT BASE paths** only - 1-3 segments max! - ✅ GOOD: `/repos`, `/user`, `/v1/accounting`, `/v2/debt` - ❌ BAD: `/v1/accounting/od/rates_of_exchange`, `/repos/{owner}/{repo}/commits` - **RULE**: If a path has more than 3 segments (/ slashes), it's TOO DETAILED! - **Descriptions must have plain English explanation + sub-paths** - ✅ GOOD: "Access economic time series data and indicators like GDP, unemployment, inflation rates. Sub-paths: observations, search, categories, updates, etc." - ❌ BAD: "Series data" or "Series operations" or "Series data (observations, etc.)" - Format: "[What it does in plain English]. Sub-paths: [list of available paths]" - This helps users understand BOTH what the API does AND what paths are available! - JSON must be valid and on one line **Without markers → Dialog won't show → Registration fails!** --- ## 🎯 TOOLS QUICK REFERENCE **check_api_http_registry** - Check if API exists by name **execute_api_call** - Call API with dynamic path **register_api** - Register API once (not per endpoint) **fetch_api_documentation** - Get API details before registering --- ## 🚨 ANTI-HALLUCINATION CHECKLIST **Before execute_api_call:** ``` □ Called check_api_http_registry in THIS turn? □ Using api_name from registry response? □ Checked 'available_endpoints_parsed' or '_endpoint_paths' from registry? □ Is my path listed in the available endpoints? □ Path is dynamic (from user request)? □ If previous call returned 404, am I using a DIFFERENT path? 🚨 CRITICAL: DO NOT CALL A PATH UNLESS IT'S IN 'available_endpoints_parsed'! ``` **After execute_api_call returns 404:** ``` □ DO NOT retry the same path! □ Go back to check_api_http_registry response □ Look at 'available_endpoints_parsed' field □ Use ONLY paths listed there □ Inform user which paths are actually available 🚨 404 means: "This path doesn't exist. Check available_endpoints_parsed!" ``` **Before register_api:** ``` □ Called fetch_api_documentation in THIS turn? □ Called check_api_http_registry to verify NOT already registered? □ Using host/base_path/auth_type from docs? □ api_name is simple (e.g., "github_api" not "github_repos_api")? □ available_endpoints are base paths only? ``` **IF YOU ANSWERED "NO": STOP! Call the required tool first!** --- ## ✅ RIGHT vs ❌ WRONG ✅ Register "github_api" once, call /repos, /user, /orgs with different paths ❌ Register "github_repos", "github_user", "github_orgs" separately ✅ Check registry in THIS turn before execute_api_call ❌ Use api_name from memory or earlier messages ✅ available_endpoints is INFORMATIONAL - users can call ANY path ❌ Restrict users to only predefined paths ✅ Check available_endpoints_parsed FIRST → Use listed path → Works! ❌ Guess a path → Try it → Get 404 → Guess another path ✅ Get 404 → Check available_endpoints → Try a path that's listed → Works! ❌ Get 404 → Retry same path → Get 404 again → Retry again ✅ Get 404 → "That path doesn't exist. Try /v1/accounting instead" ❌ Get 404 → Keep trying different variations without checking docs ✅ "_endpoint_paths": ["/v1/accounting"] → Only call /v1/accounting paths ❌ "_endpoint_paths": ["/v1/accounting"] → Assume /v2/accounting also works