stache-tools 0.1.2

Utilities and tools for the Stache RAG system

stache-tools

CLI and MCP server for the Stache knowledge base.

Installation

pip install stache-tools

This provides two commands:

• stache - CLI for interacting with your knowledge base
• stache-mcp - MCP server for Claude Desktop/Claude Code integration

Quick Start

1. Start Stache Server

See the Stache repository for full setup instructions, or quick start:

git clone https://github.com/stache-ai/stache-ai.git
cd stache
docker compose -f docker-compose.yml -f docker-compose.local.yml up -d

2. Configure MCP Server

Add to your Claude config file:

Claude Code (~/.claude.json or %APPDATA%\.claude\config.json on Windows):

{
  "mcpServers": {
    "stache-local": {
      "command": "stache-mcp",
      "env": {
        "STACHE_API_URL": "http://localhost:8000"
      }
    }
  }
}

Claude Desktop (~/.config/claude/claude_desktop_config.json or %APPDATA%\Claude\claude_desktop_config.json):

{
  "mcpServers": {
    "stache-local": {
      "command": "python",
      "args": ["-m", "stache_tools.mcp"],
      "env": {
        "STACHE_API_URL": "http://localhost:8000"
      }
    }
  }
}

3. Restart Claude

Restart Claude Code/Desktop to load the MCP server.

MCP Tools

Tool	Description
search	Semantic search in your knowledge base
ingest_text	Add text content
list_namespaces	List all namespaces
list_documents	List documents (optionally filtered by namespace)
get_document	Get document by ID
update_document	Update document metadata (filename, namespace, custom metadata)
delete_document	Delete document
create_namespace	Create namespace
get_namespace	Get namespace details
update_namespace	Update namespace properties
delete_namespace	Delete namespace

CLI Usage

# Set API URL
export STACHE_API_URL=http://localhost:8000

# Health check
stache health

# Search
stache search "your query" -n namespace -k 10

# Ingest
stache ingest ./document.pdf -n research
stache ingest ./docs/ -n documentation -r  # Recursive
stache ingest -t "Some text content" -n notes

# Namespaces
stache namespace list
stache namespace create mba/finance --name "Finance Notes"

# Documents
stache doc list -n research
stache doc get DOC_ID
stache doc update DOC_ID --filename "new-name.pdf"
stache doc update DOC_ID --new-namespace archive
stache doc update DOC_ID --metadata '{"author": "Jane Doe", "year": 2026}'
stache doc delete DOC_ID

Configuration

Variable	Description	Default
STACHE_API_URL	API base URL	http://localhost:8000
STACHE_TRANSPORT	Transport: auto, http, lambda	auto
STACHE_TIMEOUT	Request timeout (seconds)	60

AWS Lambda Transport

For direct Lambda invocation (bypasses API Gateway):

pip install stache-tools[lambda]

{
  "mcpServers": {
    "stache": {
      "command": "stache-mcp",
      "env": {
        "STACHE_LAMBDA_FUNCTION": "stache-api",
        "AWS_REGION": "us-east-1"
      }
    }
  }
}

Python API

from stache_tools import StacheAPI

with StacheAPI() as api:
    # Ingest
    api.ingest_text("Your content here", namespace="examples")

    # Search
    results = api.search("query", namespace="examples")
    for source in results.get("sources", []):
        print(f"{source['score']:.3f}: {source['content'][:100]}")

    # Document management
    docs = api.list_documents(namespace="examples")

    # Update document metadata
    api.update_document(
        doc_id="abc-123",
        namespace="default",
        updates={"filename": "renamed.pdf", "metadata": {"year": 2026}}
    )

Documentation

• Full Setup Guide - Detailed installation and configuration
• Troubleshooting - Common issues and solutions
• Stache Server - Main Stache repository

License

MIT