arcana-mcp 0.1.2

Semantic vector DB as an MCP server for Claude Code

arcana-mcp

Semantic vector DB as an MCP server for Claude Code — SQLite + FTS5 + local ONNX embeddings.

Gives Claude persistent, searchable project knowledge across conversations. Index files, store findings, search semantically — all through MCP tools.

Install

Claude Code Plugin (recommended)

claude plugin marketplace add samelie/arcana-mcp
claude plugin install arcana-mcp

This installs the MCP server, skills (/arcana:context, /arcana:absorb), and orientation protocol automatically.

Manual

pip install arcana-mcp

Add to your .mcp.json:

{
  "mcpServers": {
    "arcana": {
      "command": "uvx",
      "args": ["arcana-mcp", "serve"]
    }
  }
}

Tools

Tool	Description
arcana_add_resource	Index a file or directory into the DB
arcana_add_memory	Store a memory entry with embedding
arcana_search	Hybrid semantic + FTS5 search (best default)
arcana_find	Pure semantic (cosine similarity) search
arcana_grep	Keyword/regex search via FTS5
arcana_read	Read full content of a resource
arcana_ls	List direct children at a URI
arcana_tree	Show recursive tree at a URI
arcana_stat	Get metadata + chunk count for a resource
arcana_rm	Remove a resource (with optional recursive)
arcana_mkdir	Create a directory at a URI
arcana_mv	Move/rename a resource

Skills

/arcana:absorb <path>

Generates knowledge files optimized for Claude retrieval. Surveys a directory, synthesizes structured knowledge, and indexes it into Arcana. Re-runnable — updates stale files, removes orphans.

/arcana:context

Quick access to search, store, and browse project knowledge. Use arcana_search for hybrid search, arcana_add_memory for quick findings, arcana_add_resource for indexing files.

Configuration

Environment Variable	Default	Description
ARCANA_DB_PATH	~/.arcana/context.db	SQLite database path
ARCANA_MODEL_CACHE	~/.arcana/models	ONNX model cache directory

Architecture

• SQLite + FTS5: Full-text search with trigram tokenization
• fastembed: Local ONNX embeddings (BAAI/bge-small-en-v1.5, 384 dimensions)
• Hybrid search: 0.7 × semantic + 0.3 × FTS5 for best-of-both ranking
• Markdown chunking: Splits on # headings into ~2000 char segments
• MCP transport: stdio via FastMCP

Releasing

From the monorepo root, commit and push your changes, then run:

# Release the current version in pyproject.toml
./packages/arcana-mcp/scripts/release.sh

# Or bump + release in one step
./packages/arcana-mcp/scripts/release.sh 0.2.0

The script will:

1. Validate you're on main with a clean tree
2. Optionally bump pyproject.toml and commit
3. Wait for the monorepo sync workflow to push to samelie/arcana-mcp
4. Verify the remote version matches
5. Create a GitHub release (v0.x.x) which triggers the PyPI publish workflow

License

MIT