Skip to content

Documents

Document Management

Tools for managing files linked to memories. Files are stored as BLOBs in PostgreSQL.

upload_document

Description: Link an uploaded file to a memory. This tool is used in a two-step workflow to efficiently upload and link documents.

Two-Step Workflow:

Step 1: Upload file via REST API (curl) First, upload the file using the REST API endpoint. This avoids base64 encoding overhead and is much more efficient for large files (10MB+).

curl -X POST "https://akashic-mcp.com/api/files/upload" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "[email protected]" \
  -F "description=Project architecture" \
  -F "tags[]=architecture" \
  -F "tags[]=docs" \
  -F "category=documentation"

Response from Step 1: 

{
  "success": true,
  "file": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "filename": "architecture.pdf",
    "mime_type": "application/pdf",
    "size": 1024000,
    "description": "Project architecture",
    "tags": ["architecture", "docs"],
    "category": "documentation"
  },
  "message": "File uploaded successfully. Use upload_document MCP tool with file_id to link to a memory."
}

Step 2: Link file to memory (this MCP tool) Use the file_id from Step 1 to link the file to a memory.

Parameters: - file_id (required): The file ID returned from REST API upload (Step 1). This is the id field from the /api/files/upload response. - memory_id (required): ID of the memory to link this document to - description (optional): Description of the document. If provided, will update the file metadata. - tags (optional): Array of tags for organization. If provided, will replace existing tags. - category (optional): Category (e.g., "documentation", "diagrams", "config"). If provided, will replace existing category.

Example (Step 2): 

curl -X POST https://akashic-mcp.com/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"documents","arguments":{"action":"upload","file_id":"550e8400-e29b-41d4-a716-446655440000","memory_id":"mem-abc123","description":"Project architecture documentation","tags":["architecture","docs"],"category":"documentation"}},"id":1}'

Response: 

{
  "result": {
    "success": true,
    "file": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "memory_id": "mem-abc123",
      "filename": "architecture.pdf",
      "mime_type": "application/pdf",
      "size": 1024000,
      "description": "Project architecture documentation",
      "tags": ["architecture", "docs"],
      "category": "documentation"
    },
    "message": "Document linked to memory successfully"
  }
}

Use Cases: - Linking documentation to memories - Attaching diagrams or code examples - Storing project files with project main memory - Adding supporting materials to decisions

Why Two-Step Workflow?: - Efficient: Files uploaded directly via multipart/form-data, no base64 encoding (saves 33% space) - LLM-friendly: LLM doesn't need to handle huge base64 strings - Flexible: Can upload files first, link to memories later - Clear separation: Upload (REST) vs. Linking (MCP)

Important Notes: - Must upload file first: Use REST API to upload file and get file_id - Ownership: Can only link files that belong to your account - Can update metadata: Can update description, tags, category when linking - Maximum file size: 10MB (configurable via MAX_FILE_SIZE env var) - Supported types: Images, Documents, Text files, Archives - Documents automatically appear in retrieve_memory and search_memory results after linking

get_document

Description: Retrieve a document by its ID. Returns both metadata and file content as base64.

Parameters: - id (required): Document ID

Example: 

curl -X POST https://akashic-mcp.com/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"documents","arguments":{"action":"get","id":"file-001"}},"id":1}'

Response: 

{
  "id": "file-001",
  "memory_id": "mem-abc123",
  "filename": "architecture.pdf",
  "mime_type": "application/pdf",
  "size": 1024000,
  "description": "Project architecture documentation",
  "tags": ["architecture", "docs"],
  "category": "documentation",
  "file_content": "JVBERi0xLjQKJeLjz9MKMyAwIG9iago8PC9MZW5ndGg...",
  "created_at": "2024-01-15T10:30:00Z"
}

Use Cases: - Downloading previously uploaded documents - Accessing file content for processing - Retrieving project documentation

Important Notes: - File content is returned as base64-encoded string - Only accessible by the document owner - Use list_documents for metadata-only (faster)

list_documents

Description: List documents with optional filters. Returns metadata only (no file content) for performance.

Parameters: - memory_id (optional): Filter by memory ID - category (optional): Filter by category - tags (optional): Filter by tags (OR semantics)

Example: 

curl -X POST https://akashic-mcp.com/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"documents","arguments":{"action":"list","memory_id":"mem-abc123","category":"documentation"}},"id":1}'

Response: 

[
  {
    "id": "file-001",
    "memory_id": "mem-abc123",
    "filename": "architecture.pdf",
    "mime_type": "application/pdf",
    "size": 1024000,
    "description": "Project architecture documentation",
    "tags": ["architecture", "docs"],
    "category": "documentation",
    "created_at": "2024-01-15T10:30:00Z"
  }
]

Use Cases: - Finding all documents linked to a memory - Listing documents by category or tags - Getting document overview without loading content

Important Notes: - Returns metadata only (no file content) for performance - Use get_document to retrieve actual content when needed - Filters use OR semantics for tags

update_document_metadata

Description: Update metadata for an existing document (description, tags, category). File content cannot be updated.

Parameters: - id (required): Document ID - description (optional): Updated description - tags (optional): Updated tags array (replaces existing) - category (optional): Updated category (replaces existing)

Example: 

curl -X POST https://akashic-mcp.com/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"documents","arguments":{"action":"update_metadata","id":"file-001","description":"Updated architecture documentation","tags":["architecture","docs","updated"],"category":"documentation"}},"id":1}'

Response: 

{
  "result": "Document metadata updated successfully",
  "file_id": "file-001"
}

Use Cases: - Adding or updating document descriptions - Organizing documents with tags and categories - Correcting metadata set during upload

Important Notes: - File content and filename cannot be updated - To change content, delete and re-upload - Tags and category replace existing values (not merged)

delete_document

Description: Delete a document by its ID. This is a permanent operation.

Parameters: - id (required): Document ID

Example: 

curl -X POST https://akashic-mcp.com/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"documents","arguments":{"action":"delete","id":"file-001"}},"id":1}'

Response: 

Document deleted successfully

Use Cases: - Removing outdated documents - Cleaning up test files - Replacing documents (delete old, upload new)

Important Notes: - This operation cannot be undone - Only deletes documents belonging to the current owner - Document is permanently removed from storage