jitapi

Instructions

Implementation Reference

• src/jitapi/mcp/tools.py:403-471 (handler)

  Implementation of the get_workflow tool handler. It performs vector search, graph expansion for dependencies, fetches schemas, orders steps by dependency, and returns the workflow plan.

  async def _get_workflow(self, args: dict[str, Any]) -> ToolResult:
      """Get relevant endpoints with dependencies and schemas for a task."""
      query = args["query"]
      api_id = args["api_id"]
      max_steps = args.get("max_steps", 5)
  
      # Step 1: Vector search
      search_results = self.vector_searcher.search(query, api_id=api_id, top_k=10)
  
      if not search_results:
          return ToolResult(
              success=False,
              data=None,
              error=f"No endpoints found for query: {query}",
          )
  
      # Step 2: Graph expansion (adds dependencies the search might have missed)
      expansion = self.graph_expander.expand(
          search_results, api_id, max_depth=2, max_total=10
      )
  
      # Step 3: Collect endpoint data
      step_data = []
      step_endpoint_ids = set()
      for ep in expansion.endpoints[:max_steps]:
          endpoint = self.spec_store.get_endpoint(api_id, ep.endpoint_id)
          if endpoint:
              schema = self.schema_formatter.format_endpoint_for_call(endpoint)
              dependencies = self.graph_store.get_dependencies(api_id, ep.endpoint_id)
              step_endpoint_ids.add(ep.endpoint_id)
              step_data.append(
                  {
                      "endpoint_id": ep.endpoint_id,
                      "path": ep.path,
                      "method": ep.method,
                      "summary": ep.summary,
                      "relevance_score": round(ep.score, 3),
                      "is_dependency": ep.is_dependency,
                      "dependencies": dependencies,
                      "schema": schema,
                  }
              )
  
      # Step 4: Order steps — dependencies (providers) before dependents (consumers)
      # Simple heuristic: endpoints marked as dependencies come first,
      # then sort by relevance score within each group.
      # This handles cycles gracefully (common in auto-generated dependency graphs).
      dep_steps = [s for s in step_data if s["is_dependency"]]
      direct_steps = [s for s in step_data if not s["is_dependency"]]
      dep_steps.sort(key=lambda s: s["relevance_score"], reverse=True)
      direct_steps.sort(key=lambda s: s["relevance_score"], reverse=True)
      step_data = dep_steps + direct_steps
  
      # Number the steps
      steps = []
      for i, step in enumerate(step_data):
          step["step"] = i + 1
          steps.append(step)
  
      return ToolResult(
          success=True,
          data={
              "query": query,
              "api_id": api_id,
              "steps": steps,
              "total_endpoints": len(steps),
              "message": "Steps are ordered by dependency (prerequisites first). Use call_api to execute each step.",
          },
      )

• src/jitapi/mcp/tools.py:144-168 (schema)

  MCP definition and schema for the get_workflow tool.

      "name": "get_workflow",
      "description": "Get relevant endpoints with dependency resolution and full schemas "
      "for accomplishing a task. Returns search results expanded with their dependencies "
      "so you can plan and execute the right API calls in the right order. "
      "After reviewing the results, use call_api to execute each step.",
      "inputSchema": {
          "type": "object",
          "properties": {
              "query": {
                  "type": "string",
                  "description": "What you want to accomplish (e.g., 'create a user and place an order')",
              },
              "api_id": {
                  "type": "string",
                  "description": "The API to use",
              },
              "max_steps": {
                  "type": "integer",
                  "description": "Maximum number of endpoints to return (default: 5)",
                  "default": 5,
              },
          },
          "required": ["query", "api_id"],
      },
  },

• src/jitapi/mcp/tools.py:290-290 (registration)

  Registration of the get_workflow handler in the ToolRegistry.

  "get_workflow": self._get_workflow,