needle_add_file
Add documents to a collection by providing a URL for download, processing them for text extraction, and indexing them for semantic search.
Instructions
Add a new document to a Needle collection by providing a URL for download. Supports multiple file formats including: - PDF documents - Microsoft Word files (DOC, DOCX) - Plain text files (TXT) - Web pages (HTML)
The document will be:
1. Downloaded from the provided URL
2. Processed for text extraction
3. Indexed for semantic search
Use this tool when you need to:
- Add new documents to a collection
- Make documents searchable
- Expand your knowledge base
Important: Documents require processing time before they're searchable.
Check processing status using needle_list_files before searching new content.Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| collection_id | Yes | The unique collection identifier where the file will be added | |
| name | Yes | A descriptive filename that will help identify this document in results | |
| url | Yes | Public URL where the document can be downloaded from |
Implementation Reference
- src/needle_mcp/server.py:323-334 (handler)Executes the needle_add_file tool: validates collection_id, name, and url parameters, calls Needle client's collections.files.add() to upload the file from URL, and returns the new file ID.
elif name == "needle_add_file": if not isinstance(arguments, dict) or not all(k in arguments for k in ["collection_id", "name", "url"]): raise ValueError("Missing required parameters") if not validate_collection_id(arguments["collection_id"]): raise ValueError("Invalid collection ID format") if not validate_url(arguments["url"]): raise ValueError("Invalid URL format") files = client.collections.files.add( collection_id=arguments["collection_id"], files=[FileToAdd(name=arguments["name"], url=arguments["url"])] ) result = {"file_id": files[0].id} - src/needle_mcp/server.py:218-235 (schema)Input schema definition for needle_add_file tool, specifying required string parameters: collection_id, name, and url with descriptions.
inputSchema={ "type": "object", "properties": { "collection_id": { "type": "string", "description": "The unique collection identifier where the file will be added" }, "name": { "type": "string", "description": "A descriptive filename that will help identify this document in results" }, "url": { "type": "string", "description": "Public URL where the document can be downloaded from" } }, "required": ["collection_id", "name", "url"] } - src/needle_mcp/server.py:197-236 (registration)Registers the needle_add_file tool in the MCP server's list_tools() function with name, detailed description, and input schema.
Tool( name="needle_add_file", description="""Add a new document to a Needle collection by providing a URL for download. Supports multiple file formats including: - PDF documents - Microsoft Word files (DOC, DOCX) - Plain text files (TXT) - Web pages (HTML) The document will be: 1. Downloaded from the provided URL 2. Processed for text extraction 3. Indexed for semantic search Use this tool when you need to: - Add new documents to a collection - Make documents searchable - Expand your knowledge base Important: Documents require processing time before they're searchable. Check processing status using needle_list_files before searching new content.""", inputSchema={ "type": "object", "properties": { "collection_id": { "type": "string", "description": "The unique collection identifier where the file will be added" }, "name": { "type": "string", "description": "A descriptive filename that will help identify this document in results" }, "url": { "type": "string", "description": "Public URL where the document can be downloaded from" } }, "required": ["collection_id", "name", "url"] } ),