Metadata-Version: 2.4
Name: claude-archive-mcp
Version: 1.2.1
Summary: Local stdio MCP server exposing unified Claude chat history (claude.ai export + Claude Code sessions) as ranked, scoped, structured search.
Project-URL: Homepage, https://github.com/manderse21/claude-archive-mcp
Project-URL: Repository, https://github.com/manderse21/claude-archive-mcp
Project-URL: Issues, https://github.com/manderse21/claude-archive-mcp/issues
Project-URL: Changelog, https://github.com/manderse21/claude-archive-mcp/blob/main/CHANGELOG.md
Author-email: Mike Andersen <manderse21@gmail.com>
License: MIT
License-File: LICENSE
Keywords: archive,chat-history,claude,fts5,mcp,search,sqlite
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Utilities
Requires-Python: >=3.11
Requires-Dist: anyio>=4.0
Requires-Dist: ijson>=3.2
Requires-Dist: mcp>=1.2
Requires-Dist: numpy>=1.26
Requires-Dist: pydantic>=2.6
Provides-Extra: dev
Requires-Dist: build>=1.0; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Provides-Extra: embeddings
Requires-Dist: sentence-transformers>=3.0; extra == 'embeddings'
Provides-Extra: http
Requires-Dist: starlette>=0.40; extra == 'http'
Requires-Dist: uvicorn>=0.30; extra == 'http'
Description-Content-Type: text/markdown

# claude-archive-mcp

> Local stdio MCP server that exposes your unified Claude chat history
> (claude.ai export + Claude Code sessions) to Claude Code as ranked, scoped,
> structured search.

**Status:** v1.2.0 &middot; **Author:** Mike Andersen &middot; **License:** MIT

When you reference past work — *"did we settle this in nortam_dev last month?"*,
*"find the TAP routing analysis"*, *"what did Claude Code commit on April 14?"* —
Claude Code reaches for this server instead of asking you to summarize.

## Two sources, one index

| Source | `source` | Origin |
|---|---|---|
| claude.ai export | `claude_ai` | `~/.claude/Exported_Chats/conversations.json` + `projects/` |
| Claude Code sessions | `claude_code` | `~/.claude/projects/**/*.jsonl` |

Both feed one `conversations` table; the same tools search across both.

## Tools

`search_chats` &middot; `get_chat` &middot; `list_projects` &middot; `list_recent_chats` &middot;
`search_within_chat` &middot; `archive_stats` &middot; `timeline` &middot; `find_related_chats` &middot;
`get_digest` &middot; `recall` &middot; `get_session_lineage` — eleven read-only, source-aware tools.
See [`docs/TOOLS.md`](docs/TOOLS.md). The server also exposes a per-project **resource**
(`claude-archive://project/{source}/{identifier}`) — a dynamic markdown project overview.

**Digest:** `get_digest` (tool) or `python scripts/digest.py --weekly` (also `/digest`) — a
markdown activity recap over a rolling daily/weekly window; both share one aggregator.

**Semantic search (optional):** `find_related_chats` ranks conversations by embedding
cosine. It needs the optional extra — `pip install -e .[embeddings]`, then
`python scripts/embed.py --backfill` (also `/embed`). The server itself stays inference-free.

## Install

See [`docs/INSTALL.md`](docs/INSTALL.md). In short (Windows, PowerShell 7):

```powershell
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -e .[dev]
python scripts\reindex.py        # build the index from both sources
python scripts\install_mcp.py    # register the server in ~/.claude.json
```

Then start a new Claude Code session and ask away (see INSTALL.md for details).

## Web viewer (read-only, localhost)

A plain, server-rendered web UI for browsing the same index in a browser — a second,
read-only *consumer* of the query layer (it adds no MCP tool and changes no contract).

```powershell
python -m claude_archive_mcp.webui                 # opens http://127.0.0.1:8766/
python -m claude_archive_mcp.webui --port 9000     # same, on a different port
```

- **Pages (six):** Home (recent conversations), Search (full-text, ranked), Conversation
  (with within-chat search **and** a Related-conversations section via embedding
  similarity), Timeline (a topic's activity over time, filterable by source/project),
  Digest (rolling daily/weekly activity digest), and Stats (archive statistics with
  near-duplicate project names collapsed for reading). The query logic is reused from the
  same handlers the MCP tools wrap — no duplicate logic, no MCP transport.
- **Posture (all enforced in code, proven by tests):** binds `127.0.0.1` **only** (no
  config to widen it); opens the SQLite DB `mode=ro`, so it can never write or migrate;
  GET-only; no JavaScript; stdlib `http.server` (no extra dependencies).
- **Port:** defaults to `8766`; override with `CLAUDE_ARCHIVE_WEBUI_PORT` or the `--port`
  flag (the flag wins). The **host is a hard rail** — `--port` changes the port only,
  never the loopback bind. Index first (`python scripts\reindex.py`) — the viewer reads an
  existing DB and will not create one.

## Documentation

- [`docs/CONTRACT.md`](docs/CONTRACT.md) — the frozen 1.0 surface + the 1.x semver policy
- [`docs/INSTALL.md`](docs/INSTALL.md) — Windows install walkthrough
- [`docs/TOOLS.md`](docs/TOOLS.md) — per-tool reference + examples
- [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) — design + rationale
- [`docs/SOURCES.md`](docs/SOURCES.md) — how each source is parsed, edge cases
- [`CHANGELOG.md`](CHANGELOG.md)

## Development

```powershell
pip install -e .[dev]
ruff check .
ruff format --check .
mypy --strict src/
pytest
```

Conventions live in [`CLAUDE.md`](CLAUDE.md). The project is built in gated
phases; do not chain past a phase gate.
