FastAPI OpenAPI MCP Server

Instructions

Implementation Reference

• openapi_mcp/tools/search.py:83-169 (handler)

  The execute method of SearchEndpointsTool that implements the core logic: validates params, searches OpenAPI spec, formats and returns results.
  async def execute(self, **kwargs: Any) -> CallToolResult: """执行搜索工具逻辑 从 OpenAPI schema 中搜索匹配条件的接口， 支持多种搜索方式，并格式化为 Markdown 输出。 Args: **kwargs: 搜索参数 Returns: 包含搜索结果的 CallToolResult """ try: # 验证参数 validation_result = self._validate_params(kwargs) if validation_result: return validation_result # 获取搜索参数 keyword = kwargs.get('keyword', '').strip() regex = kwargs.get('regex', '').strip() # 获取 OpenAPI spec spec = self.get_openapi_spec() # 执行搜索 results = self._search_endpoints_advanced(spec, **kwargs) # 限制结果数量 limit = kwargs.get('limit', 50) if len(results) > limit: results = results[:limit] truncated = True else: truncated = False # 格式化输出 - 即使没有结果也要传递搜索信息 keyword_or_regex = keyword or regex search_in_param = kwargs.get('search_in', 'all') if not results and keyword_or_regex: # 创建一个假结果对象用于格式化，只包含搜索信息 fake_results = [ { 'keyword': keyword_or_regex, 'search_in': search_in_param, 'method': '', 'path': '', 'summary': '', 'description': '', 'tags': '', 'matched_in': '', 'deprecated': False, } ] # 检查formatter类型并调用相应方法 if ( hasattr(self._formatter, '__class__') and 'Markdown' in self._formatter.__class__.__name__ ): output = self._formatter.format_search_results( results=fake_results, truncated=truncated, empty_results=True, ) else: output = self._formatter.format_search_results(fake_results) else: # 检查formatter类型并调用相应方法 if ( hasattr(self._formatter, '__class__') and 'Markdown' in self._formatter.__class__.__name__ ): output = self._formatter.format_search_results( results=results, truncated=truncated ) else: output = self._formatter.format_search_results(results) return CallToolResult(content=[TextContent(type='text', text=output)]) except Exception as e: error_msg = f'❌ 错误: 搜索失败 - {type(e).__name__}: {e}' return CallToolResult( content=[TextContent(type='text', text=error_msg)], isError=True )
• openapi_mcp/tools/search.py:29-81 (schema)

  Input schema defining parameters for keyword, regex, search scope, filters, and limits.
  input_schema = { 'type': 'object', 'properties': { 'keyword': { 'type': 'string', 'description': '搜索关键词（支持模糊匹配，不区分大小写）', }, 'search_in': { 'type': 'string', 'description': '搜索范围', 'enum': ['path', 'summary', 'description', 'tags', 'all'], 'default': 'all', }, 'regex': { 'type': 'string', 'description': '正则表达式搜索（与 keyword 互斥）', }, 'tags': { 'type': 'array', 'items': {'type': 'string'}, 'description': '按标签过滤，支持多个标签（OR 关系）', }, 'methods': { 'type': 'array', 'items': { 'type': 'string', 'enum': [ 'GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'HEAD', 'OPTIONS', ], }, 'description': '按 HTTP 方法过滤，支持多个方法', }, 'include_deprecated': { 'type': 'boolean', 'description': '是否包含已废弃的接口', 'default': False, }, 'limit': { 'type': 'integer', 'minimum': 1, 'maximum': 100, 'description': '返回结果数量限制', 'default': 50, }, }, 'required': [], }
• openapi_mcp/server.py:155-160 (registration)

  Registration of SearchEndpointsTool instance in OpenApiMcpServer's builtin tools list during initialization.
  from openapi_mcp.tools.examples import GenerateExampleTool from openapi_mcp.tools.search import SearchEndpointsTool # 注册 Tools self.tools.append(SearchEndpointsTool(self)) # 增强的搜索工具 self.tools.append(GenerateExampleTool(self)) # 新增的示例生成工具
• openapi_mcp/tools/search.py:237-336 (helper)

  Helper method that performs the advanced endpoint search by iterating over OpenAPI paths, applying filters, and matching search criteria.
  def _search_endpoints_advanced( self, spec: dict[str, Any], **kwargs ) -> list[dict[str, Any]]: """高级搜索接口 Args: spec: OpenAPI specification 字典 **kwargs: 搜索参数 Returns: 匹配的接口列表 """ results: list[dict[str, Any]] = [] paths = spec.get('paths', {}) # 获取搜索参数 keyword = kwargs.get('keyword', '').strip() regex = kwargs.get('regex', '').strip() search_in = kwargs.get('search_in', 'all').lower() tags_filter = kwargs.get('tags', []) methods_filter = [m.upper() for m in kwargs.get('methods', [])] include_deprecated = kwargs.get('include_deprecated', False) # 编译正则表达式 regex_pattern = re.compile(regex, re.IGNORECASE) if regex else None keyword_lower = keyword.lower() if keyword else None # 用于格式化的搜索词显示 search_term_display = keyword or regex for path, methods in paths.items(): if not isinstance(methods, dict): continue for method, info in methods.items(): # 只处理标准 HTTP 方法 method_upper = method.upper() if method_upper not in [ 'GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'HEAD', 'OPTIONS', ]: continue if not isinstance(info, dict): continue # 方法过滤 if methods_filter and method_upper not in methods_filter: continue # 废弃接口过滤 if not include_deprecated and info.get('deprecated', False): continue # 获取接口信息 summary = info.get('summary', '') or '' description = info.get('description', '') or '' tags = [t for t in info.get('tags', []) if isinstance(t, str)] # 标签过滤 if tags_filter: if not any(tag in tags_filter for tag in tags): continue # 执行搜索 matched_in = self._check_match_advanced( path, summary, description, tags, keyword_lower, regex_pattern, search_in, ) if matched_in: results.append( { 'method': method_upper, 'path': path, 'summary': summary, 'description': description, 'tags': ', '.join(tags), 'matched_in': matched_in, 'deprecated': info.get('deprecated', False), 'keyword': search_term_display, 'search_in': search_in, } ) # 按路径和方法排序 results.sort(key=lambda x: (x['path'], x['method'])) return results