taskflow-doc-search 0.1.0__py3-none-any.whl

doc_search/__init__.py

@@ -0,0 +1 @@
+"""Documentation search tools served over MCP stdio."""

doc_search/embeddings.py

@@ -0,0 +1,192 @@
+"""Section embeddings with a content-validated, local derived index.
+
+Importing this module does not import sentence-transformers or torch.
+The fake embedder is a deterministic test double, not a semantic model.
+"""
+import hashlib
+import json
+import math
+import os
+import re
+from functools import lru_cache
+from pathlib import Path
+
+from .server import ROOT
+
+# Keep the checkout cache beside the compatibility launcher, even when the
+# workspace is overridden. Installed packages cache under the workspace,
+# avoiding writes to site-packages.
+_SERVER_DIR = Path(__file__).resolve().parents[1]
+INDEX_DIR = (
+    _SERVER_DIR if (_SERVER_DIR / "server.py").is_file()
+    else ROOT / "mcp" / "doc-search"
+) / ".index"
+DEFAULT_MODEL = "sentence-transformers/all-MiniLM-L6-v2"
+
+
+class _FakeEmbedder:
+    def encode(self, texts):
+        from .server import _tokenize
+
+        vectors = []
+        for text in texts:
+            vector = [0.0] * 64
+            for token in _tokenize(text):
+                slot = int(hashlib.sha256(token.encode("utf-8")).hexdigest(), 16) % 64
+                vector[slot] += 1.0
+            norm = math.sqrt(sum(v * v for v in vector))
+            vectors.append([v / norm for v in vector] if norm else vector)
+        return vectors
+
+
+class _RealEmbedder:
+    def __init__(self, model):
+        try:
+            from sentence_transformers import SentenceTransformer
+        except ImportError as exc:
+            raise RuntimeError(
+                "sentence-transformers is not installed; "
+                "install the optional embeddings dependencies with: "
+                "pip install taskflow-doc-search[embeddings]"
+            ) from exc
+        self.model = SentenceTransformer(model)
+
+    def encode(self, texts):
+        return self.model.encode(texts, normalize_embeddings=True).tolist()
+
+
+@lru_cache(maxsize=2)
+def _embedder(name, model):
+    if name == "fake":
+        return _FakeEmbedder()
+    if name != "sentence-transformers":
+        raise ValueError(f"unknown DOC_SEARCH_EMBEDDER: {name}")
+    return _RealEmbedder(model)
+
+
+def get_embedder():
+    """Return the configured embedder, loading the real model only on demand."""
+    return _embedder(
+        os.environ.get("DOC_SEARCH_EMBEDDER", "sentence-transformers"),
+        os.environ.get("DOC_SEARCH_EMBEDDING_MODEL", DEFAULT_MODEL),
+    )
+
+
+def chunk_document(path, text):
+    """Split ATX sections into body chunks carrying their full heading trail.
+
+    The preamble uses the document title. Empty section bodies are retained
+    so a heading alone remains searchable. Fenced code is treated as body.
+    """
+    from .server import ROOT, _doc_title
+
+    path = Path(path)
+    title = _doc_title(text, path)
+    relative = path.relative_to(ROOT).as_posix()
+    chunks, trail, body = [], [], []
+    heading = title
+    fence = None
+
+    def flush():
+        chunks.append({"path": relative, "title": title,
+                       "heading": heading, "text": "\n".join(body).strip()})
+
+    for line in text.splitlines():
+        marker = re.match(r"^ {0,3}(`{3,}|~{3,})(.*)$", line)
+        if marker:
+            run, tail = marker.groups()
+            if fence is None:
+                fence = run
+            elif run[0] == fence[0] and len(run) >= len(fence) and not tail.strip():
+                fence = None
+            body.append(line)
+            continue
+        match = None if fence else re.match(r"^ {0,3}(#{1,6})(?:[ \t]+(.*)|$)", line)
+        if match:
+            if trail or any(part.strip() for part in body):
+                flush()
+            level = len(match[1])
+            label = re.sub(r"[ \t]+#+[ \t]*$", "", match[2] or "").strip()
+            trail = [(n, label_) for n, label_ in trail if n < level]
+            trail.append((level, label))
+            heading = " > ".join(label_ for _, label_ in trail)
+            body = []
+        else:
+            body.append(line)
+    if trail or any(part.strip() for part in body):
+        flush()
+    return chunks
+
+
+def build_index(documents, manifest):
+    """Embed a byte snapshot of the corpus and persist its derived cache."""
+    chunks = []
+    for path, content in documents:
+        chunks.extend(chunk_document(path, content.decode("utf-8", errors="replace")))
+    if chunks:
+        vectors = get_embedder().encode([
+            f"{c['title']} > {c['heading']}\n{c['text']}" for c in chunks
+        ])
+        for chunk, vector in zip(chunks, vectors):
+            chunk["embedding"] = vector
+    INDEX_DIR.mkdir(parents=True, exist_ok=True)
+    (INDEX_DIR / "chunks.jsonl").write_text(
+        "".join(json.dumps(c, ensure_ascii=False) + "\n" for c in chunks),
+        encoding="utf-8",
+    )
+    (INDEX_DIR / "manifest.json").write_text(
+        json.dumps({**manifest, "chunk_count": len(chunks)}, indent=2), encoding="utf-8"
+    )
+    return chunks
+
+
+def load_index():
+    """Reuse the cache only when corpus bytes, model and embedder match."""
+    from .server import ROOT, _iter_docs
+
+    documents = [(p, p.read_bytes()) for p in _iter_docs()]
+    hashes = sorted((p.relative_to(ROOT).as_posix(), hashlib.sha256(b).hexdigest())
+                    for p, b in documents)
+    manifest = {
+        "model": os.environ.get("DOC_SEARCH_EMBEDDING_MODEL", DEFAULT_MODEL),
+        "embedder": os.environ.get("DOC_SEARCH_EMBEDDER", "sentence-transformers"),
+        "fingerprint": hashlib.sha256(json.dumps(hashes).encode("utf-8")).hexdigest(),
+    }
+    try:
+        saved = json.loads((INDEX_DIR / "manifest.json").read_text(encoding="utf-8"))
+        if all(saved.get(k) == v for k, v in manifest.items()):
+            chunks = [json.loads(line) for line in
+                      (INDEX_DIR / "chunks.jsonl").read_text(encoding="utf-8").splitlines()]
+            if len(chunks) == saved.get("chunk_count"):
+                return chunks
+    except (OSError, ValueError):
+        pass
+    return build_index(documents, manifest)
+
+
+def search(query, limit=8):
+    """Rank section chunks by pure-Python cosine; cache writes are local."""
+    from .server import _tokenize
+
+    if limit <= 0 or not _tokenize(query):
+        return []
+    chunks = load_index()
+    if not chunks:
+        return []
+    vector = get_embedder().encode([query])[0]
+    norm = math.sqrt(sum(v * v for v in vector))
+    results = []
+    for chunk in chunks:
+        other = chunk["embedding"]
+        denominator = norm * math.sqrt(sum(v * v for v in other))
+        score = round(sum(a * b for a, b in zip(vector, other)) / denominator, 4) if denominator else 0
+        if not score:
+            continue
+        results.append({
+            "path": chunk["path"], "title": chunk["title"], "score": score,
+            "snippet": next((line.strip()[:200] for line in chunk["text"].splitlines()
+                             if line.strip()), ""),
+            "heading": chunk["heading"],
+        })
+    results.sort(key=lambda r: (-r["score"], r["path"], r["heading"]))
+    return results[:limit]

doc_search/server.py

@@ -0,0 +1,336 @@
+"""doc-search — an MCP server for the ai-workspace-kit workspace.
+
+Tools (local documents, no credentials; embeddings maintains a derived cache):
+
+- search_docs(query)   keyword search across the documentation repos that
+                       sync checked out under projects/
+- search_docs_semantic(query)
+                       TF-IDF vector-space search over the same corpus
+- search_docs_embeddings(query)
+                       section embeddings over the same corpus; lazily loaded,
+                       with a derived cache in the server's .index/ directory
+- get_doc(path)        fetch one document by workspace-relative path
+- list_tickets(status) list the pre-TF-115 Markdown archive in tickets/
+- propose_ticket(title, body)
+                       write a ticket DRAFT under tickets/drafts/ — the
+                       server's only content write, draft-first by construction:
+                       it can never create or modify a real ticket; a human
+                       files an Issue via scripts/promote-draft
+
+Workspace root resolution: the AI_WORKSPACE_ROOT environment variable wins;
+otherwise the server assumes it lives at <root>/mcp/doc-search/server.py.
+
+Run (stdio):  python server.py
+"""
+import math
+import os
+import re
+import sys
+from collections import Counter
+from pathlib import Path
+
+from fastmcp import FastMCP
+
+
+def _force_utf8_stdio() -> None:
+    """Force UTF-8 on stdin/stdout/stderr.
+
+    On Windows machines whose system locale is not UTF-8 (e.g. Chinese
+    Windows defaults Python's stdio to GBK), a stdio MCP server otherwise
+    emits non-UTF-8 bytes. Strict hosts (Codex's rmcp launcher) read the
+    streams as UTF-8, fail to decode them, and tear the connection down
+    during the initialize handshake. Pinning UTF-8 here makes the server
+    behave identically on any locale. Clients can also set PYTHONUTF8=1
+    in the server env; doing both is harmless.
+    """
+    for stream in (sys.stdin, sys.stdout, sys.stderr):
+        reconfigure = getattr(stream, "reconfigure", None)
+        if reconfigure is not None:
+            try:
+                reconfigure(encoding="utf-8", errors="replace")
+            except (ValueError, OSError):
+                pass
+
+
+_force_utf8_stdio()
+
+
+def workspace_root() -> Path:
+    env = os.environ.get("AI_WORKSPACE_ROOT")
+    if env:
+        return Path(env).resolve()
+    return Path(__file__).resolve().parents[3]
+
+
+ROOT = workspace_root()
+PROJECTS_DIR = ROOT / "projects"
+TICKETS_DIR = ROOT / "tickets"
+
+# These are dependency installs and tool caches, never content directories;
+# adding a name is a deliberate corpus change.
+EXCLUDED_DIR_NAMES = {".git", ".venv", "venv", "node_modules", "__pycache__", ".pytest_cache"}
+
+mcp = FastMCP("doc-search")
+
+
+def _iter_docs():
+    if not PROJECTS_DIR.exists():
+        return
+    for p in sorted(PROJECTS_DIR.rglob("*.md")):
+        if EXCLUDED_DIR_NAMES.intersection(p.parts):
+            continue
+        yield p
+
+
+def _doc_title(text: str, path: Path) -> str:
+    for line in text.splitlines():
+        if line.startswith("# "):
+            return line[2:].strip()
+    return path.stem
+
+
+# The search/read tools read local documents; embeddings also writes a
+# derived local cache (and may download its model on first use). Declaring that in the MCP
+# annotations matters: clients such as Codex auto-approve read-only
+# tools but stop un-annotated ones for manual approval (and refuse them
+# outright in non-interactive runs).
+READ_ONLY = {"readOnlyHint": True, "destructiveHint": False, "openWorldHint": False}
+
+# The one write tool (propose_ticket) is annotated honestly as a write:
+# clients will ask the user before running it, which is exactly the
+# human-in-the-loop point of draft-first.
+DRAFT_WRITE = {"readOnlyHint": False, "destructiveHint": False, "openWorldHint": False}
+
+
+@mcp.tool(annotations=READ_ONLY)
+def search_docs(query: str, limit: int = 8) -> list[dict]:
+    """Keyword search over the workspace documentation repos.
+
+    Ranking is deliberately simple and inspectable: a hit in a document
+    title counts 3, in a heading 2, in body text 1. Returns workspace-
+    relative path, title, score, and the first matching line as a snippet.
+    """
+    terms = [t for t in re.split(r"\W+", query.lower()) if t]
+    if not terms:
+        return []
+    results = []
+    for p in _iter_docs():
+        text = p.read_text(encoding="utf-8", errors="replace")
+        title = _doc_title(text, p)
+        score = sum(3 * title.lower().count(t) for t in terms)
+        snippet = ""
+        for line in text.splitlines():
+            low = line.lower()
+            hits = sum(low.count(t) for t in terms)
+            if not hits:
+                continue
+            score += 2 * hits if line.lstrip().startswith("#") else hits
+            if not snippet:
+                snippet = line.strip()[:200]
+        if score:
+            results.append(
+                {
+                    "path": p.relative_to(ROOT).as_posix(),
+                    "title": title,
+                    "score": score,
+                    "snippet": snippet,
+                }
+            )
+    results.sort(key=lambda r: (-r["score"], r["path"]))
+    return results[:limit]
+
+
+def _tokenize(text: str) -> list[str]:
+    return [t for t in re.split(r"\W+", text.lower()) if t]
+
+
+@mcp.tool(annotations=READ_ONLY)
+def search_docs_semantic(query: str, limit: int = 8) -> list[dict]:
+    """Vector-space (TF-IDF, cosine similarity) search over the docs.
+
+    The contrast with search_docs is deliberate. Keyword search counts
+    exact hits with hand-set weights (title x3, heading x2, body x1), so
+    a document that repeats a common term many times can outrank the
+    topically closest one. Here each document is a TF-IDF vector: terms
+    that appear in many documents (low information) are down-weighted by
+    the IDF factor, and ranking is by cosine similarity to the query
+    vector, i.e. overall topical closeness across all query terms.
+
+    It is still a bag-of-words model - no synonym or embedding magic.
+    Pure stdlib; the corpus is re-indexed on every call, which is fine
+    at documentation-repo scale and keeps the server stateless.
+    """
+    query_tokens = _tokenize(query)
+    if not query_tokens:
+        return []
+    docs = []
+    for p in _iter_docs():
+        text = p.read_text(encoding="utf-8", errors="replace")
+        docs.append((p, text, _tokenize(text)))
+    if not docs:
+        return []
+
+    n = len(docs)
+    doc_freq: Counter = Counter()
+    for _, _, tokens in docs:
+        doc_freq.update(set(tokens))
+    idf = {t: math.log((n + 1) / (c + 1)) + 1.0 for t, c in doc_freq.items()}
+
+    def vectorize(tokens: list[str]) -> dict[str, float]:
+        counts = Counter(tokens)
+        total = max(len(tokens), 1)
+        return {t: (c / total) * idf[t] for t, c in counts.items() if t in idf}
+
+    query_vec = vectorize(query_tokens)
+    query_norm = math.sqrt(sum(v * v for v in query_vec.values()))
+    if not query_norm:
+        return []
+
+    results = []
+    for p, text, tokens in docs:
+        doc_vec = vectorize(tokens)
+        dot = sum(query_vec[t] * doc_vec.get(t, 0.0) for t in query_vec)
+        doc_norm = math.sqrt(sum(v * v for v in doc_vec.values()))
+        if not doc_norm or dot <= 0:
+            continue
+        snippet = ""
+        terms = set(query_tokens)
+        for line in text.splitlines():
+            if terms & set(_tokenize(line)):
+                snippet = line.strip()[:200]
+                break
+        results.append(
+            {
+                "path": p.relative_to(ROOT).as_posix(),
+                "title": _doc_title(text, p),
+                "score": round(dot / (query_norm * doc_norm), 4),
+                "snippet": snippet,
+            }
+        )
+    results.sort(key=lambda r: (-r["score"], r["path"]))
+    return results[:limit]
+
+
+@mcp.tool(annotations=READ_ONLY)
+def search_docs_embeddings(query: str, limit: int = 8) -> list[dict]:
+    """Search document sections using locally computed sentence embeddings.
+
+    Returns path, title, cosine score rounded to four places, the first
+    non-empty body line (up to 200 characters) as snippet, and heading trail.
+    Writes only a derived cache in this server's .index/ directory. The
+    optional model downloads on first use, then runs locally. Model imports
+    are deferred until this tool is called, keeping startup torch-free.
+    """
+    from . import embeddings
+
+    return embeddings.search(query, limit)
+
+
+@mcp.tool(annotations=READ_ONLY)
+def get_doc(path: str) -> str:
+    """Fetch one Markdown document by workspace-relative path, e.g.
+    "projects/taskflow-docs/system-overview.md" or "tickets/TF-101.md".
+    Paths outside projects/ and tickets/ are refused.
+    """
+    target = (ROOT / path).resolve()
+    allowed = [PROJECTS_DIR.resolve(), TICKETS_DIR.resolve()]
+    if (
+        target.suffix != ".md"
+        or not target.exists()
+        or not any(str(target).startswith(str(a)) for a in allowed)
+    ):
+        raise ValueError(f"document not found or not allowed: {path}")
+    return target.read_text(encoding="utf-8", errors="replace")
+
+
+def _parse_ticket(p: Path) -> dict:
+    text = p.read_text(encoding="utf-8", errors="replace")
+    meta: dict[str, str] = {}
+    if text.startswith("---"):
+        parts = text.split("---", 2)
+        if len(parts) >= 3:
+            for line in parts[1].splitlines():
+                if ":" in line:
+                    k, v = line.split(":", 1)
+                    meta[k.strip()] = v.strip()
+    return {
+        "id": meta.get("id", p.stem),
+        "title": meta.get("title", ""),
+        "status": meta.get("status", ""),
+        "priority": meta.get("priority", ""),
+        "path": p.relative_to(ROOT).as_posix(),
+    }
+
+
+@mcp.tool(annotations=READ_ONLY)
+def list_tickets(status: str | None = None) -> list[dict]:
+    """List the pre-TF-115 archive (Markdown files in tickets/).
+    Optionally filter by status: open, in-progress, done. New work lives
+    in GitHub Issues; humans promote drafts via scripts/promote-draft.
+    """
+    out = []
+    if TICKETS_DIR.exists():
+        for p in sorted(TICKETS_DIR.glob("*.md")):
+            t = _parse_ticket(p)
+            if status and t["status"] != status:
+                continue
+            out.append(t)
+    return out
+
+
+@mcp.tool(annotations=DRAFT_WRITE)
+def propose_ticket(title: str, body: str, priority: str = "medium") -> dict:
+    """Propose a new ticket as a DRAFT under tickets/drafts/.
+
+    Draft-first is enforced here, not left to convention: this is the
+    server's only write tool, and it can only create a new file in
+    tickets/drafts/ with status "draft". It cannot create, modify, or
+    delete the pre-TF-115 archive in tickets/. A human reviews the draft
+    and files an Issue via scripts/promote-draft if it should become
+    a ticket. The server stays credential-free. Returns the workspace-relative
+    path.
+    """
+    # One line, and no "---": the ticket parser splits front matter on
+    # that marker, so a title containing it would corrupt the draft.
+    clean_title = " ".join(title.split()).replace("---", "-")
+    slug = re.sub(r"[^a-z0-9]+", "-", clean_title.lower()).strip("-")[:60]
+    slug = slug.strip("-") or "untitled"
+    if priority not in ("low", "medium", "high"):
+        raise ValueError("priority must be low, medium or high")
+    drafts_dir = TICKETS_DIR / "drafts"
+    drafts_dir.mkdir(parents=True, exist_ok=True)
+    path = drafts_dir / f"draft-{slug}.md"
+    if path.exists():
+        raise ValueError(
+            f"a draft already exists at tickets/drafts/{path.name};"
+            " choose a different title"
+        )
+    text = (
+        "---\n"
+        f"id: draft-{slug}\n"
+        f"title: {clean_title}\n"
+        "status: draft\n"
+        f"priority: {priority}\n"
+        "---\n\n"
+        f"{body.strip()}\n"
+    )
+    path.write_text(text, encoding="utf-8")
+    return {
+        "path": path.relative_to(ROOT).as_posix(),
+        "status": "draft",
+        "note": (
+            "Draft only: a human must review it and file an Issue via"
+            " scripts/promote-draft; tickets/ is the pre-TF-115 archive."
+        ),
+    }
+
+
+def main() -> None:
+    # No startup banner: a stdio server should keep stderr quiet, and the
+    # banner's box-drawing characters are exactly the kind of non-ASCII
+    # output that breaks under non-UTF-8 locales (see _force_utf8_stdio).
+    mcp.run(show_banner=False)  # stdio transport by default
+
+
+if __name__ == "__main__":
+    main()

taskflow_doc_search-0.1.0.dist-info/METADATA

@@ -0,0 +1,137 @@
+Metadata-Version: 2.4
+Name: taskflow-doc-search
+Version: 0.1.0
+Summary: MCP server for keyword search over the ai-workspace-kit documentation repos and demo tickets
+License-Expression: MIT
+Project-URL: Repository, https://github.com/cynthiawang109-sudo/ai-workspace-kit
+Project-URL: Documentation, https://github.com/cynthiawang109-sudo/ai-workspace-kit/tree/main/mcp/doc-search
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastmcp>=4.1.7
+Provides-Extra: dev
+Requires-Dist: pytest>=9.2.0; extra == "dev"
+Provides-Extra: embeddings
+Requires-Dist: sentence-transformers>=3; extra == "embeddings"
+Dynamic: license-file
+
+# doc-search MCP server
+
+A small [MCP](https://modelcontextprotocol.io) server written with FastMCP.
+It gives an AI coding agent structured access to this workspace's
+documentation and demo tickets — the local, public stand-in for the
+Jira/Confluence side of the original production workspace. Five tools are
+annotated read-only (embeddings maintains a derived local cache); the sixth can only write ticket *drafts* (see below).
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `search_docs(query, limit=8)` | Keyword search across every Markdown doc under `projects/`; title hits ×3, heading hits ×2, body hits ×1; returns path, title, score, snippet |
+| `search_docs_semantic(query, limit=8)` | TF-IDF vector-space search over the same corpus (cosine similarity); returns path, title, score (0–1), snippet |
+| `search_docs_embeddings(query, limit=8)` | Sentence embeddings over heading chunks; returns path, title, cosine score, snippet, heading; caches in `.index/` |
+| `get_doc(path)` | Fetch one document by workspace-relative path (only `projects/` and `tickets/` are readable) |
+| `list_tickets(status?)` | List the pre-TF-115 archive from `tickets/*.md` front matter, optionally filtered by status |
+| `propose_ticket(title, body, priority="medium")` | Write a ticket **draft** to `tickets/drafts/draft-<slug>.md` — the server's only source-content write; it cannot create or modify real tickets |
+
+## Draft-first writes
+
+`propose_ticket` mirrors the production workspace's rule for outward
+writes (there: Jira changes start as drafts a human approves). The
+boundary is enforced by the tool, not by politeness: it writes only
+new files under `tickets/drafts/`, always with `status: draft`, it
+refuses to overwrite an existing draft, and it is annotated as a
+write, so clients ask the user before calling it. `tickets/` is the pre-TF-115
+archive; `list_tickets` never shows drafts as tickets. A human reviews and
+promotes a draft with `scripts/promote-draft.ps1` (or `.sh`), which files
+an Issue instead of moving the file into `tickets/`. Set `AI_WORKSPACE_PROJECT`
+to the workspace Project number, or pass `-Project N` / `--project N`, to
+also add the Issue to the board. Without a Project, the script prints the
+Issue URL and notes that it was not added to a board. The draft is preserved.
+The doc-search server stays credential-free and never calls GitHub.
+
+## Three rungs of document search
+
+1. `search_docs` counts exact term hits with title/heading/body weights.
+   It is predictable for known terms, but repetition can dominate ranking.
+2. `search_docs_semantic` uses TF-IDF cosine similarity over whole documents.
+   It down-weights common terms and balances multi-term queries. Both of
+   these first two rungs are bag-of-words models: neither understands synonyms.
+   They use only the standard library and rebuild their vectors per call.
+3. `search_docs_embeddings` uses sentence-transformers over ATX heading
+   sections, embedding the document title, heading trail and body. It can
+   retrieve paraphrases and synonyms, but relevance is model-dependent.
+   Cosine ranking uses pure Python. A content-hash fingerprint invalidates
+   the derived `.index/` cache when documents or the model change.
+
+- **Local documents**: searches never modify the source documents. Embeddings
+  writes a derived cache; `propose_ticket` writes drafts under the rules above.
+- **No credentials**: keyword and TF-IDF need no network. Embeddings downloads
+  its model once, then runs fully locally.
+- **Client-agnostic**: plain MCP over stdio.
+
+## Setup
+
+```powershell
+cd mcp\doc-search
+python -m venv .venv
+.venv\Scripts\python -m pip install -r requirements.txt pytest
+```
+
+Optional embeddings dependencies (includes torch):
+
+```powershell
+.venv\Scripts\python -m pip install -r requirements-embeddings.txt
+```
+
+`DOC_SEARCH_EMBEDDING_MODEL` overrides the default
+`sentence-transformers/all-MiniLM-L6-v2`. `DOC_SEARCH_EMBEDDER=fake` selects
+only a deterministic hashed-token test double, without semantic understanding.
+
+Evaluate the synced corpus with `python scripts/run_eval.py`; add `--write`
+to record the dated results in [EVAL.md](EVAL.md). The eval is not run in CI.
+
+## Run the tests
+
+```powershell
+.venv\Scripts\python -m pytest
+```
+
+The tests build a throwaway fixture workspace, so they pass whether or not
+`sync` has populated `projects/`.
+
+## Register it
+
+**Codex** — add to `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.doc-search]
+command = 'C:\path\to\ai-workspace-kit\mcp\doc-search\.venv\Scripts\python.exe'
+args = ['C:\path\to\ai-workspace-kit\mcp\doc-search\server.py']
+```
+
+**Claude Code**:
+
+```powershell
+claude mcp add doc-search -- C:\path\to\ai-workspace-kit\mcp\doc-search\.venv\Scripts\python.exe C:\path\to\ai-workspace-kit\mcp\doc-search\server.py
+```
+
+The server finds the workspace root from its own location
+(`<root>/mcp/doc-search/server.py`); set `AI_WORKSPACE_ROOT` to override.
+
+
+## Install the distribution
+
+Once published, install with `pip install taskflow-doc-search` (or
+`pip install "taskflow-doc-search[embeddings]"` for sentence embeddings).
+For a local checkout, `pip install .` from this directory works today.
+Run `taskflow-doc-search` with `AI_WORKSPACE_ROOT` set to the absolute path
+of the workspace to search. It serves MCP over stdio; no command arguments
+are needed. The existing `python server.py` launcher and its automatic
+workspace-root detection remain supported.
+
+Release instructions: [PUBLISHING.md](PUBLISHING.md).
+The included [server.json](server.json) is prepared for an optional MCP
+registry listing and has not been published.
+
+<!-- mcp-name: io.github.cynthiawang109-sudo/taskflow-doc-search -->

taskflow_doc_search-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+doc_search/__init__.py,sha256=IMwKvHk4stxVESkd9exVdyNtX35CV5DZpUvMgA83Zkc,56
+doc_search/embeddings.py,sha256=4fEtlhSSTegJS93aElY_0sgucCd_a1X3ITVvW1ySzhw,6963
+doc_search/server.py,sha256=7SQcamb8FkTcCq3T5KX5ZFnGMwF_5EOyi8-FYFhPOD8,12529
+taskflow_doc_search-0.1.0.dist-info/licenses/LICENSE,sha256=oZK015jWgItvrrP5jytEfeTcAdL0q1oWjSQel7-40VA,1069
+taskflow_doc_search-0.1.0.dist-info/METADATA,sha256=QzBWvQZ0y2TewzzgI9KWws0J2UAEVc_nVg4rV-29UlI,6347
+taskflow_doc_search-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+taskflow_doc_search-0.1.0.dist-info/entry_points.txt,sha256=X2XRafobqIZr_Kmc0P9ZH0OdmprSdPMOcOzGJhgHOKk,63
+taskflow_doc_search-0.1.0.dist-info/top_level.txt,sha256=ZnrU1qKAxzuXmSW7FrEmIm-w6mqu_ZjTcgIzWLFvN4E,11
+taskflow_doc_search-0.1.0.dist-info/RECORD,,

taskflow_doc_search-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

taskflow_doc_search-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+taskflow-doc-search = doc_search.server:main

taskflow_doc_search-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cynthia Wang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

taskflow_doc_search-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+doc_search