# Glyph Hold MCP connector

Version 2.2.0 is a local stdio MCP server for Codex and other MCP clients. It uses
Glyph Hold 2's public `/api/v2` HTTP API and never opens the server's SQLite file.
Upgrade this connector alongside the server; version 0.1.0 is for GH1.

## Setup

Use Python 3.12+ and install locally with `pip install -e ".[dev]"`. The FastMCP
SDK dependency is pinned below major version 2 because that major changes the
server API. Configure `.env` or your MCP host environment:

```text
GLYPHHOLD_URL=https://your-glyphhold-host.example.com
GLYPHHOLD_API_KEY=gh_live_xxxxxxxxxxxxxxxxx
```

Existing timeout/TLS options in `.env.example` remain supported. In GH2 create
the API key, assign its explicit space grants and default destination, and grant
only required scopes: `memories:read`, `memories:write`, `secrets:write`, and
`secrets:reveal`. API-level admin scope does not grant all spaces. Run
`glyphhold-mcp` as the stdio command in your host's MCP configuration, with the
checkout's environment and Python executable. No live host configuration is
changed by this source upgrade.

## Contract

- `glyphhold_capabilities` reports permitted spaces and the connection default.
- `prefetch_memories` returns bounded active/General context with IDs, versions,
  ownership, provenance and freshness.
- `search_memories` accepts explicit broader discovery. A result in another space
  does not change the write destination.
- `create_memory` requires a stable idempotency key. Reuse it for retries.
- `update_memory`, `archive_memory`, `move_memory` and `restore_memory_revision`
  require the last-read expected version. Reread after HTTP 409 conflicts.
- `get_memory_context`, `set_memory_context` and `get_placement_guidance` support
  deliberate per-conversation routing and owner-confirmed associations. Supply
  the same unique session ID to context, search/recall and create operations.
- Secret metadata and explicit per-secret reveal remain separate and work with
  built-in or Vaultwarden providers. Secrets are global and independent of memory spaces.
- Destructive delete, bulk environment reveal and lexical conflict claims are
  removed from this GH2 surface.

Tool failures remain structured ordinary payloads so a missing record or conflict
never invalidates the entire connector. Source content and credentials are not
included in error logs. Tool availability alone cannot guarantee pre-response
recall: configure the host workflow or use a native memory-provider integration.

Run `python -m pytest tests`. Tests validate tool schemas, error containment,
transport safety, idempotent/versioned writes and explicit reveal paths. The GH2
checkout also has local cross-repository ASGI conformance tests covering this
client, Hermes and Nexus against the actual backend. Live host setup and network
connectivity still need a deployment rehearsal.

## Live secret providers (2.1)

With Vaultwarden enabled, search and metadata read all accessible vault entries
directly, including pre-existing items. Built-in secrets remain accessible.
Secret `space_id` is accepted for compatibility but no longer scopes access;
API keys still require secret permissions. Memory spaces are unchanged.

`create_secret` uses the active provider and rejects duplicate names. Optional
`folder_id` chooses a vault folder; omission uses the configured default and an
empty string means unfiled. `list_secret_folders` and `create_secret_folder`
manage optional folders. No memory-to-folder mapping or item linking is needed.

`reveal_secret(field=...)` selects a field from metadata (password, username,
SSH keys, notes, card/identity or custom fields). `update_secret` requires the
current metadata version and preserves other fields. External changes cannot
be made atomically against concurrent edits in other Bitwarden clients.

`migrate_secret` transfers a built-in secret without exposing its value to the
agent. Search first: provide an existing `target_id` and field to verify equal
values, or omit target ID to create only when the name is unused. Conflicts
retain both values for user review; never blindly overwrite or export plaintext.
Provider outages fail explicitly rather than look like an empty vault. Upgrade
the server and adapters together to use these operations.

### 2.1.3 search and migration recovery

`search_secrets(query=...)` also matches saved website addresses and hostnames,
including IP addresses. Metadata adds `websites` (normalised origins only) and
`hostnames`; URL usernames/passwords, paths, query tokens and fragments are
excluded. Multiple accounts stay separate; never select one by hostname alone.
Use `provider_name=builtin` for the remaining migration checklist.

`migrate_secret(dry_run=true)` checks an existing field or previews creation
without changing either provider. Known provider failure codes produce safe,
actionable tool errors; arbitrary error bodies are not echoed. An uncertain
write requires destination inspection before retrying.

## Selective recall (2.2)

Automatic recall supplies a small relevant starting context. An empty result does
not mean that no matching memories exist; even a nonempty result can concern the
wrong entity or space. Search explicitly for missing personal facts, try shorter
terms or synonyms, and broaden deliberately for another permitted space. Read the
full record by ID when an excerpt omits evidence. Tool parameters are unchanged.