Shared core for schema-driven MCP servers over Russian business APIs: catalog, safety gating, HTTP client, credential store
Server provides 13 well-structured tools with consistent naming (verb_noun pattern: check_auth, list_sections, get_section, search_methods, describe_method, call_method, write_method, delete_method, get_raw, write_raw, delete_raw, fetch_all, map). All tools have descriptions (50-200 chars, within baseline). Input schemas are present with type definitions and parameter descriptions. However, output schemas are not formally documented, responses are JSON strings without declared structure. Error handling is minimal (no recovery guidance, no error classification). Tool annotations present (readOnlyHint, destructiveHint via naming convention). Composition is strong: tools chain well (search → describe → call), and destructive operations are separated from reads. Parameter descriptions are adequate but lack constraint details (e.g., limit ranges, enum values for method types). No pagination metadata in responses (total_count, next_cursor). Security: credentials handled server-side via client.config, not exposed as parameters.
Execute a read-only catalog endpoint with the given parameters. Returns the marketplace response or an error envelope.
Check whether the required credentials are present in the environment. Does NOT reveal secret values — only reports which variables are set. Returns JSON: {"ready": bool, "missing": [str], "required": [str]}.
Execute a destructive catalog endpoint (DELETE) with confirmation. Returns the marketplace response or an error envelope.
Execute a DELETE request on any path (confirmed). Returns the marketplace response or an error envelope.
Return the full catalog record for one endpoint: method, host, path, scope, safety level, pagination style, rate limit, params and doc URL.
Output schemas not formally documented. Tools return JSON strings without declared structure (e.g., {svc}_list_sections returns {sections, total_endpoints} but this is not in a schema). LLMs cannot plan downstream calls or extract fields reliably.
Error handling lacks recovery guidance. Errors return JSON with 'error' and 'message' fields but do not suggest next steps (e.g., 'No section found' should suggest 'Call {svc}_list_sections to see available sections'). Agents cannot self-correct.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-23 | C | 63 | 2026-07-28+ | v2 |
Auto-paginate a catalog endpoint and return all items. Handles multiple pagination styles (offset, cursor, last_id, page, etc.). Returns all items or truncates at max_items/max_pages.
Execute a GET/HEAD/OPTIONS request on any path (full coverage). Returns the marketplace response or an error envelope.
List all endpoints in one section. Args: section: section name (see {svc}_list_sections), e.g. "statistics". Returns JSON list of {operation_id, method, path, safety, summary}.
List API sections and how many catalog endpoints each contains.
The big picture: business entities this API covers and the go-to methods for each. Call with no args to see the whole map ("you are here"); pass entity="reviews" (or stocks/prices/orders/…) to list every method of one entity. Use this before guessing — it orients you fast.
Search the endpoint catalog by keyword (works in Russian and English). Args: query: free text, e.g. "остатки", "stocks", "update price". limit: max results (1-50). Returns JSON list of matching endpoints (best first).
Execute a write catalog endpoint (POST/PUT/PATCH) with confirmation. Returns the marketplace response or an error envelope.
Execute a POST/PUT/PATCH request on any path (confirmed). Returns the marketplace response or an error envelope.
Parameter constraints not fully specified. 'limit' in {svc}_search_methods has default=15 and description mentions '1-50', but no min/max in schema. 'path_values' and 'query' in {svc}_call_method are type:object with no structure guidance, LLMs cannot infer what keys are valid.
Pagination not exposed in responses. {svc}_fetch_all handles pagination internally but does not return pagination metadata (total_count, next_cursor, has_more). Agents cannot know if results are truncated or plan multi-page workflows.
Tool descriptions lack dependency hints. {svc}_describe_method and {svc}_call_method do not explain that users should call {svc}_search_methods or {svc}_get_section first to discover operation_ids. This forces agents to guess the discovery sequence.