getSpecDefinition

Instructions

Implementation Reference

• tools/postman_tools.py:1064-1089 (handler)

  The GetSpecDefinitionTool class is the handler for the getSpecDefinition tool. It defines the class, schema, and execution logic. The run_tool method makes a GET request to /apis/{specId}/definition to retrieve the complete definition of an API specification.

  class GetSpecDefinitionTool(ToolHandler):
      """Get spec definition contents"""
      
      def __init__(self):
          super().__init__("getSpecDefinition")
      
      def get_tool_description(self) -> Tool:
          return Tool(
              name=self.name,
              description="Gets the complete contents of an API spec's definition.",
              inputSchema={
                  "type": "object",
                  "properties": {
                      "specId": {
                          "type": "string",
                          "description": "Spec ID"
                      }
                  },
                  "required": ["specId"]
              },
          )
      
      async def run_tool(self, args: dict) -> list[TextContent]:
          spec_id = args["specId"]
          result = await postman_api_call("GET", f"/apis/{spec_id}/definition")
          return [TextContent(type="text", text=json.dumps(result, indent=2))]

• tools/postman_tools.py:1070-1084 (schema)

  Input schema for getSpecDefinition: requires a 'specId' (string) property describing the specification ID.

  def get_tool_description(self) -> Tool:
      return Tool(
          name=self.name,
          description="Gets the complete contents of an API spec's definition.",
          inputSchema={
              "type": "object",
              "properties": {
                  "specId": {
                      "type": "string",
                      "description": "Spec ID"
                  }
              },
              "required": ["specId"]
          },
      )

• tools/postman_tools.py:1869-1892 (registration)

  Registration of GetSpecDefinitionTool() in the register_all_tools function (line 1869) which returns all tool handler instances.

      GetSpecDefinitionTool(),
      CreateSpecFileTool(),
      GetSpecFilesTool(),
      GetSpecFileTool(),
      UpdateSpecFileTool(),
      
      # Spec-Collection Integration
      GenerateCollectionTool(),
      GetSpecCollectionsTool(),
      GenerateSpecFromCollectionTool(),
      GetGeneratedCollectionSpecsTool(),
      SyncCollectionWithSpecTool(),
      SyncSpecWithCollectionTool(),
      
      # Workspaces
      CreateWorkspaceTool(),
      GetWorkspaceTool(),
      GetWorkspacesTool(),
      UpdateWorkspaceTool(),
      
      # Other
      GetTaggedEntitiesTool(),
      RunCollectionTool(),
  ]

• tests/test_postman.py:81-81 (registration)

  Test file references getSpecDefinition as one of the expected tool names in test_tool_names() to verify it is registered.

  "getSpecDefinition",

• tools/toolhandler.py:9-23 (helper)

  ToolHandler is the abstract base class that GetSpecDefinitionTool extends. It provides the __init__ (sets self.name), abstract get_tool_description(), and abstract run_tool() methods.

  class ToolHandler(ABC):
      """Base class for all Postman tool handlers"""
      
      def __init__(self, name: str):
          self.name = name
      
      @abstractmethod
      def get_tool_description(self) -> Tool:
          """Return the MCP Tool description for this handler"""
          pass
      
      @abstractmethod
      async def run_tool(self, arguments: dict) -> list[TextContent | ImageContent | EmbeddedResource]:
          """Execute the tool with the given arguments"""
          pass