Metadata-Version: 2.4
Name: mcp-temporal-knowledge
Version: 0.4.0
Summary: Temporal Knowledge Substrate MCP Server — domain-scoped knowledge accumulation with tool-enforced temporal integrity
Requires-Python: >=3.10
Requires-Dist: fastmcp>=2.0.0
Requires-Dist: neo4j>=5.26.0
Requires-Dist: pydantic>=2.10.1
Requires-Dist: starlette>=0.28.0
Description-Content-Type: text/markdown

# Temporal Knowledge Substrate

An MCP server that lets LLM agents accumulate organizational knowledge across sessions, scoped by domain, backed by Neo4j. Tools enforce structural invariants so the graph can't corrupt itself — no raw Cypher writes.

**Two-layer architecture:**
- **Process layer** (immutable) — Domains own Runs, Runs chain forward in time via NEXT_RUN. The arrow of time is enforced by the tool, not by instructions.
- **Knowledge layer** (append-only) — 10 entity types (System, Process, Configuration, Gotcha, Rationale, etc.) connected by 7 relationship types. Knowledge evolves via EVOLVED_FROM chains — old versions are preserved, never overwritten.

## Prerequisites

- Python 3.10+
- [uv](https://docs.astral.sh/uv/) package manager
- Neo4j 5.x instance (local or remote)

## Quick Start

```bash
# Install
uv sync

# Run (stdio transport, default for MCP clients)
mcp-temporal-knowledge --db-url bolt://localhost:7687
```

## Configuration

All options can be set via CLI flags or environment variables. CLI takes precedence.

| CLI Flag | Env Var | Default | Description |
|---|---|---|---|
| `--db-url` | `NEO4J_URI` or `NEO4J_URL` | `bolt://localhost:7687` | Neo4j connection URL |
| `--username` | `NEO4J_USERNAME` | `neo4j` | Neo4j username |
| `--password` | `NEO4J_PASSWORD` | `password` | Neo4j password |
| `--database` | `NEO4J_DATABASE` | `neo4j` | Neo4j database name |
| `--transport` | `NEO4J_TRANSPORT` | `stdio` | Transport: `stdio`, `sse`, or `streamable-http` |
| `--namespace` | `NEO4J_NAMESPACE` | *(none)* | Tool name prefix (e.g. `myapp` -> `myapp-begin_session`) |
| `--server-host` | `NEO4J_MCP_SERVER_HOST` | `127.0.0.1` | HTTP host (non-stdio transports) |
| `--server-port` | `NEO4J_MCP_SERVER_PORT` | `8000` | HTTP port (non-stdio transports) |
| `--server-path` | `NEO4J_MCP_SERVER_PATH` | `/mcp/` | HTTP path (non-stdio transports) |

## MCP Client Configuration

### Claude Desktop / Claude Code

Add to your MCP config:

```json
{
  "mcpServers": {
    "temporal-knowledge": {
      "command": "mcp-temporal-knowledge",
      "args": ["--db-url", "bolt://localhost:7687"]
    }
  }
}
```

### HTTP transport

```bash
mcp-temporal-knowledge \
  --db-url bolt://localhost:7687 \
  --transport streamable-http \
  --server-host 0.0.0.0 \
  --server-port 8000 \
  --allow-origins "http://localhost:3000" \
  --allowed-hosts "localhost,127.0.0.1"
```

## Tool Surface (20 tools)

### Session workflow

Every session follows: `create_domain` (once) -> `begin_session` -> create/evolve/confirm knowledge -> `end_session`

| Tool | Description |
|---|---|
| `list_domains` | List all domains with run counts and last activity |
| `create_domain` | Create a knowledge domain (idempotent) |
| `begin_session` | Start a session — returns `run_id` needed by all knowledge tools |
| `end_session` | Close a session with a summary of what was learned |

### Knowledge mutation

| Tool | Description |
|---|---|
| `create_knowledge` | Create entities (System, Gotcha, Rationale, etc.) linked to the current session |
| `evolve_knowledge` | Create a new version of an entity — old version preserved via EVOLVED_FROM |
| `confirm_knowledge` | Record that entities were reviewed and found unchanged |
| `create_connections` | Link entities (ENABLING, REQUIRING, CAUSING, etc.) |

### Querying

| Tool | Description |
|---|---|
| `search_knowledge` | Fulltext search across names and descriptions |
| `get_domain_state` | All current (head-of-chain) entities for a domain |
| `get_run_history` | Session history — who worked on what, when |
| `read_cypher` | Read-only Cypher escape hatch (writes rejected) |

### Taxonomy & Analytics

| Tool | Description |
|---|---|
| `list_knowledge_types` | The 10 entity types with descriptions |
| `list_connection_types` | The 7 knowledge + 4 process edge types |
| `gds_create_projection` | Create a GDS graph projection for analytics |
| `gds_drop_projection` | Drop a GDS projection |
| `gds_pagerank` | PageRank centrality |
| `gds_betweenness` | Betweenness centrality (bridge nodes) |
| `gds_louvain` | Louvain community detection |
| `gds_wcc` | Weakly connected components |

## Development

```bash
# Install with dev dependencies
uv sync --dev

# Run tests
uv run pytest

# Type checking
uv run pyright
```

See `SPEC.md` for the full architecture specification, graph schema, and Cypher templates.
