Needle MCP Server

Instructions

Implementation Reference

• src/needle_mcp/server.py:317-322 (handler)

  The handler logic for the 'needle_list_files' tool within the call_tool dispatcher function. It validates the collection_id argument, lists files using the Needle client, and formats the response as a dictionary of files with id, name, and status.

  elif name == "needle_list_files":
      if not isinstance(arguments, dict) or "collection_id" not in arguments:
          raise ValueError("Missing required parameter: 'collection_id'")
      files = client.collections.files.list(arguments["collection_id"])
      result = {"files": [{"id": f.id, "name": f.name, "status": f.status} for f in files]}

• src/needle_mcp/server.py:173-196 (registration)

  Registration of the 'needle_list_files' tool in the list_tools() function, including the tool name, description, and input schema definition.

  Tool(
      name="needle_list_files",
      description="""List all documents stored within a specific Needle collection with their current status.
      Returns detailed information about each file including:
      - File ID and name
      - Processing status (pending, processing, complete, error)
      - Upload date and metadata
      Use this tool when you need to:
      - Inventory available documents
      - Check processing status of uploads
      - Get file IDs for reference
      - Verify document availability before searching
      Essential for monitoring document processing completion before performing searches.""",
      inputSchema={
          "type": "object",
          "properties": {
              "collection_id": {
                  "type": "string",
                  "description": "The unique collection identifier to list files from"
              }
          },
          "required": ["collection_id"]
      }
  ),

• src/needle_mcp/server.py:186-195 (schema)

  Input schema definition for the 'needle_list_files' tool, specifying the required 'collection_id' parameter.

  inputSchema={
      "type": "object",
      "properties": {
          "collection_id": {
              "type": "string",
              "description": "The unique collection identifier to list files from"
          }
      },
      "required": ["collection_id"]
  }