Skip to main content
Glama
Sign In
internal-swagger-mcp

internal-swagger-mcp

by zhangwanli09
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Hybrid

Search Swagger API

swagger_search_api
Read-only

Search internal Swagger API interfaces by keyword across names, descriptions, paths, and modules, with optional filters for HTTP method and service to quickly locate relevant endpoints.

Instructions

Search API interfaces in the internal Swagger documentation.

Searches by keyword across interface name, description, path, and module name. Optionally filter by HTTP method and service.

Parameters:

  • keyword (required): Search keyword, e.g. "登录", "user", "/api/order". Chinese is supported.

  • method (optional): HTTP method filter, e.g. "GET", "POST".

  • source (optional): Service name filter, taken from swagger_list_sources results.

  • include_deprecated (optional): Whether to include deprecated interfaces. Default false.

  • limit (optional): Maximum number of results. Default 20.

Response: Each matched interface includes: service name, module name, HTTP method, full path, interface name, description, status.

Examples:

  • Search login interfaces: keyword="登录"

  • Search POST interfaces: keyword="用户", method="POST"

  • Search within a specific service: keyword="order", source="订单服务"

Input Schema

NameRequiredDescriptionDefault
limitNoMaximum number of results. Default 20, max 50.
methodNoFilter by HTTP method. Omit to search all methods.
sourceNoRestrict the search to a specific service name (from swagger_list_sources). Omit to search all services.
keywordYesSearch keyword. Matches interface name / description / path / module name. Chinese is supported.
include_deprecatedNoWhether to include deprecated interfaces. Default false.

Output Schema

NameRequiredDescriptionDefault
totalYes
failedNo
keywordYes
resultsYes
truncatedYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed4 schema fields changedv2.1.0
    • changedInput schema / $schema
      Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
    • changedOutput schema / $schema
      Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
    • addedOutput schema / properties / total / maximum
      Added value: +9007199254740991
    • addedOutput schema / properties / total / minimum
      Added value: +-9007199254740991
  2. First observedv1.0.5

TDQS

A4.4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly/openWorld/non-destructive, so the safety profile is covered. The description adds real context: the response field list, the default of 20 results, and that deprecated interfaces are excluded unless include_deprecated is set — a meaningful scoping behavior not in the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded purpose sentence followed by scoped bullets, response shape, and examples — well organized. There is mild redundancy between the parameter bullets and the schema descriptions, and the examples partially repeat the parameter text, keeping it from a 5.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 5-parameter search tool with annotations, full schema coverage, and an output schema, everything needed to select and invoke it correctly is present: matching scope, filters, defaults, and result shape.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3. The description goes beyond the schema by giving illustrative keyword values (CJK text, path fragments like '/api/order') and tying source to swagger_list_sources output, which helps an agent construct valid calls.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (search) and resource (API interfaces in internal Swagger docs) plus the exact fields matched (name, description, path, module). This clearly distinguishes it from swagger_list_sources (enumerate) and swagger_get_api_detail (fetch one), which are named separately in the parameter docs.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explains how to filter by method and service, and explicitly ties the source filter to 'results from swagger_list_sources', establishing the intended call order. It gives three concrete query examples. It stops short of explicitly saying when to switch to swagger_get_api_detail for full detail, so not quite a 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools