# Reported issues for Deadzone

Pod holds 16 of 21 problems reported by people outside the maintainer team. Issues filed by the project's own owners, members and collaborators are excluded entirely — a maintainer's release checklist is not a warning to a prospective user.

Back to [Deadzone](/mcp/deadzone).

## Most discussed

### Project diagnostic: competitive landscape, premise challenge, and contributor roadmap

## Context

I spent time analyzing Deadzone's positioning, architecture, and contribution opportunities. This is a summary of the findings, meant to start a conversation about the project's direction.

## Project Diagnostic — 5 Premises Challenged

### Premise 1: Developers need semantic search on library docs — VALID but crowded

At least 7 serious alternatives exist as of April 2026:
- **Context7** (Upstash): first mover, 65% contextual accuracy, reduced free tier to 1000 req/month
- **Deepcon

[Read the thread](https://github.com/laradji/deadzone/issues/40) · 2026-04-10 · closed · external user · 4 comments

### Doc ingestion architecture — tracking issue

> **🔒 STATUS — CLOSED 2026-04-11**
>
> This tracking issue is closed and **superseded** by the architectural decision log at [`docs/research/ingestion-architecture.md`](https://github.com/laradji/deadzone/blob/main/docs/research/ingestion-architecture.md).
>
> The mvp milestone closed alongside this issue with all 7 sub-issues merged: #27, #28, #30, #44, #51, #58, #60. The end-to-end pipeline (`libraries_sources.yaml` → `scrape-via-agent` → artifacts → consolidate → `search_libraries`/`search_do

[Read the thread](https://github.com/laradji/deadzone/issues/15) · 2026-04-10 · closed · 2 comments

### update(deps): bump hugot v0.7.0 to v0.7.2 and mcp go-sdk v1.5.0 to v1.6.0

Parent: #156
Depends on: none
Related: audit §5.2 finding 2, §8 action item 24

## Why

Two outdated direct deps surfaced by `go list -m -u all` during the
audit:

```
github.com/knights-analytics/hugot         v0.7.0  → v0.7.2 (patch +2)
github.com/modelcontextprotocol/go-sdk     v1.5.0  → v1.6.0 (minor +1)
```

Patch bumps for `hugot` are likely bug fixes; the `go-sdk` minor bump
may include feature changes affecting `cmd/deadzone/server.go`'s MCP
wiring.

## Decision (locked 2026-04-30)

- Bu

[Read the thread](https://github.com/laradji/deadzone/issues/167) · 2026-04-30 · closed · 1 comment

### registry: normalize `versions:` keys to major.minor, decouple from git ref via `ref:`

Depends on: #113, #115, #118

## Why

`libraries_sources.yaml` currently uses the git tag verbatim as the `versions:` map key, which couples two concerns:

- **User-facing identifier** (what the LLM sees in `search_libraries` output and passes to `search_docs`)
- **Git tag string** (what the scraper needs to fetch raw files)

This leaks three different formats across the 12 libs and makes LLM UX awkward:

| Lib | Current | Problem |
|---|---|---|
| `/ovh/go-ovh` | `v1.9.0` | `v` prefix + full se

[Read the thread](https://github.com/laradji/deadzone/issues/120) · 2026-04-14 · closed · 1 comment

### fix: remove dead Topic field from SearchDocsInput MCP schema

## Problem

`SearchDocsInput` in `cmd/server/main.go:17` declares a `Topic string` field with jsonschema tag `"topic or section to focus on (optional)"`. The README also advertises it: "topic — optional section filter (not yet implemented)".

But `makeSearchHandler` (line 38-76) never reads `input.Topic`. The field is silently ignored. Every MCP client that connects sees this parameter in the tool schema, may use it, and gets zero filtering.

A parameter that exists in the schema but does nothin

[Read the thread](https://github.com/laradji/deadzone/issues/39) · 2026-04-10 · closed · external user · 1 comment

### feat: add list_libraries MCP tool for library discovery

## Problem

MCP clients (Claude Code, Cursor, etc.) have no way to discover which libraries are indexed in the local Deadzone database. The only tool exposed is `search_docs`, which requires knowing a `lib_id` upfront.

Context7, the hosted alternative, exposes a `resolve-library-id` tool for this purpose (documented in `docs/research/context7-analysis.md`).

## Proposed solution

Add a `list_libraries` MCP tool that returns all indexed libraries:

```sql
SELECT DISTINCT lib_id FROM docs
```

Re

[Read the thread](https://github.com/laradji/deadzone/issues/36) · 2026-04-10 · closed · external user · 1 comment

### feat(ci): auto-publish to MCP Registry via mcp-publisher on tag push

**Decision (locked 2026-05-07)**

- Auth method: `github-oidc` — no PAT, no Ed25519 key, no rotating secret. Required workflow permission: `id-token: write`. Source: [`docs/modelcontextprotocol-io/github-actions.mdx`](https://github.com/modelcontextprotocol/registry/blob/main/docs/modelcontextprotocol-io/github-actions.mdx) recommends OIDC over the PAT and DNS variants.
- Trigger: `workflow_run` chained off `docker-publish.yml` succeeded + manual `workflow_dispatch` for hotfixes. The MCP Registr

[Read the thread](https://github.com/laradji/deadzone/issues/220) · 2026-05-07 · open · 0 comments

### feat(docker): bake hugot embedder model weights into the OCI image (close the --network none gap from #203)

**Depends on:** none. **Follows:** #203 (DB baked into the OCI image). **Touches:** `Dockerfile`, `.github/workflows/scrape-pack.yml` (docker job staging step), `README.md`.

## Why

#203 baked `deadzone.db` + `deadzone.db.release` sidecar + `libonnxruntime` into the OCI image, set `DEADZONE_DB_OFFLINE=1`, and dropped the named-volume mount from the README's MCP wire-up. The README now claims:

> first launch is instant — no download, no volume mount, no `--network` access required

This is **no

[Read the thread](https://github.com/laradji/deadzone/issues/207) · 2026-05-05 · closed · 0 comments

## Most recent

### feat: publish OCI image to GHCR alongside existing release artifacts

**Depends on:** none. **Supersedes:** none. **Parent:** none.

## Why

The official MCP Registry (`registry.modelcontextprotocol.io`, launched 2025-09) only accepts five package types: `npm`, `pypi`, `nuget`, `oci` (Docker Hub), and `oci` (GHCR). It does **not** support raw GitHub Releases binaries. Today deadzone ships exclusively as native tarballs + AppImages + a Homebrew tap — none of which the official registry can discover.

Adding an OCI image published to **GHCR** on every tag is the che

[Read the thread](https://github.com/laradji/deadzone/issues/196) · 2026-05-04 · closed · 0 comments

### tweak: surface 'aggregation' in /open-telemetry/opentelemetry description

**Decision (locked 2026-05-03):** Update the description for `/open-telemetry/opentelemetry` in `libraries_sources.yaml` to surface "aggregation" honestly. Trivial YAML edit, follows from the manual verification block of #191.

## Why

Query `"log aggregation system"` against the v0.5.0 corpus (post-#192 description-mixing) returned the 5 Grafana products in top 5 but `/open-telemetry/opentelemetry` was absent. Result captured in the [verification comment on #191](https://github.com/laradji/dead

[Read the thread](https://github.com/laradji/deadzone/issues/195) · 2026-05-03 · closed · 0 comments

### fix(db): `deadzone server` cannot coexist with another running server — #131's contract is broken in practice

**Parent:** none
**Supersedes:** none
**Related:** #131 (the original "split reader vs mutator" feature whose contract this issue exposes as broken)

## Summary (the bug in one paragraph)

`deadzone server` cannot run as a second process when another `deadzone server` is already running against the same `deadzone.db`. The second invocation fails with:

```
deadzone: open db: open db reader /Users/.../deadzone.db: set query_only:
turso: error: Locking error: Failed locking file. File is locked by

[Read the thread](https://github.com/laradji/deadzone/issues/172) · 2026-05-01 · closed · 0 comments

### scraper+db+mcp: first-class multi-version support (version column + -lib/-version split)

Parent: n/a
Depends on: #103

## Why

Today when a lib has `versions: [v1.14, v1.13]`, the scraper concats the version into `lib_id` (`/hashicorp/terraform/v1.14`, `/hashicorp/terraform/v1.13`) and the DB stores them as two unrelated-looking rows. The MCP client has no structured way to ask "search terraform v1.14 only" or "list versions of terraform" — it has to infer from the path suffix, which is opaque to the LLM and fragile.

Concretely broken today:
- `search_docs` does `WHERE lib_id = ?` 

[Read the thread](https://github.com/laradji/deadzone/issues/113) · 2026-04-14 · closed · 0 comments

### scraper/packs: folder-per-lib layout + retire per-artifact release, ship deadzone.db only

**Decision (locked 2026-04-13):** two coordinated changes, one PR.

**(1) Local layout:** replace flat `artifacts/<slug>.db` + `<slug>.db.state` with per-lib folder `artifacts/<slug>/` containing `artifact.db` (+ WAL/SHM during runs) and `state.yaml`.

**(2) Release model:** stop publishing per-lib artifacts to GitHub Releases. Only the consolidated `deadzone.db` ships, uploaded **manually from the operator's laptop** for now (CI no longer runs `packs download` + `consolidate`). The per-artifact

[Read the thread](https://github.com/laradji/deadzone/issues/101) · 2026-04-13 · closed · 0 comments

### Add `search_libraries` MCP tool — semantic lib_id resolution at Context7 scale

Add a `search_libraries` MCP tool that resolves a free-text library name into a small ranked list of canonical lib_ids the user can then pass to `search_docs`. The resolution is powered by a **dedicated SQL vector table** — symmetric with how `search_docs` already works on `docs.embedding`.

**Parent:** #15
**Replaces:** #36 (closed — flat list approach didn't scale)
**Composes with:** #28 (per-lib artifacts) and #45 (vector index)

## Why a flat `list_libraries` is not enough

Deadzone targets 

[Read the thread](https://github.com/laradji/deadzone/issues/44) · 2026-04-10 · closed · 0 comments

### Structured logging for the MCP server and scraper (slog on stderr, JSON output)

Both Deadzone binaries currently have minimal logging. `cmd/server` only emits two `log.Fatal` calls at startup — no trace of incoming `search_docs` requests, query parameters, result counts, latency, or errors. `cmd/scraper` has two human-readable progress lines and otherwise silently fetches, parses, and indexes. Neither binary is debuggable today without rebuilding with extra prints.

This issue wires structured JSON logging into **both** binaries using the same pattern, so operators see cons

[Read the thread](https://github.com/laradji/deadzone/issues/24) · 2026-04-10 · closed · 0 comments

### First push to GitHub remote (open source)

Publish the initial Deadzone code to GitHub.

**Done:**
- Created public repo `github.com/laradji/deadzone`
- `.gitignore` hardening: added `/deadzone-server` (binary) and `.claude/` (personal Claude Code config) on top of existing `CLAUDE.md`, `.mcp.json`, `.envrc`, `/deadzone.db`
- Verified zero sensitive files tracked (`git ls-files | grep -E '(CLAUDE|\.mcp|\.envrc|deadzone-server|\.claude)'` empty)
- SSH config: added `Host github.com` block in `~/.ssh/config` with `IdentityFile ~/.ssh/id_ed

[Read the thread](https://github.com/laradji/deadzone/issues/12) · 2026-04-10 · closed · 0 comments

The remaining reports are on [the project's issue tracker](https://github.com/laradji/deadzone/issues).