contextweave-mcp 0.2.0__py3-none-any.whl

contextweave/agents/agents_md/__init__.py

@@ -0,0 +1,3 @@
+from contextweave.agents.agents_md.adapter import AgentsMdAdapter
+
+__all__ = ["AgentsMdAdapter"]

contextweave/agents/agents_md/adapter.py

@@ -0,0 +1,57 @@
+from collections.abc import Mapping
+from pathlib import Path
+
+from contextweave.agents.base import (
+    FileChange,
+    HookSpec,
+    InstallOpts,
+    apply_changes,
+    plan_change,
+    read_exact,
+)
+from contextweave.agents.claude_code.files import merge_mcp, unmerge_mcp
+from contextweave.agents.memory_block import plan_block_install, plan_block_removal
+
+MCP_FILE = ".mcp.json"
+MEMORY_FILE = "AGENTS.md"
+
+
+def _changes(candidates: list[FileChange | None]) -> list[FileChange]:
+    return [change for change in candidates if change is not None]
+
+
+class AgentsMdAdapter:
+    """Generic agents: .mcp.json and an AGENTS.md routing block, no hooks."""
+
+    name = "agents_md"
+
+    def detect(self, root: Path) -> bool:
+        return (root / MEMORY_FILE).exists()
+
+    def hook_events(self) -> Mapping[str, HookSpec]:
+        return {}
+
+    def install(self, root: Path, opts: InstallOpts) -> list[FileChange]:
+        mcp_path = root / MCP_FILE
+        changes = _changes(
+            [
+                plan_change(mcp_path, merge_mcp(read_exact(mcp_path), mcp_path)),
+                plan_block_install(root / MEMORY_FILE),
+            ]
+        )
+        if not opts.dry_run:
+            apply_changes(changes, root)
+        return changes
+
+    def uninstall(self, root: Path, opts: InstallOpts) -> list[FileChange]:
+        mcp_path = root / MCP_FILE
+        mcp = read_exact(mcp_path)
+        changes = _changes(
+            [
+                plan_change(mcp_path, unmerge_mcp(mcp, mcp_path)) if mcp is not None else None,
+                plan_block_removal(root / MEMORY_FILE),
+            ]
+        )
+        if not opts.dry_run:
+            apply_changes(changes, root)
+        return changes

contextweave/agents/base.py

@@ -0,0 +1,109 @@
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Protocol
+
+from contextweave.core.registry import Registry
+
+
+@dataclass(frozen=True, slots=True)
+class InstallOpts:
+    """Options for one install or uninstall; home and env locate user-level agent config."""
+
+    home: Path
+    plugin: bool = False
+    plugin_dir: Path | None = None
+    dry_run: bool = False
+    env: Mapping[str, str] = field(default_factory=dict[str, str])
+
+
+@dataclass(frozen=True, slots=True)
+class FileChange:
+    """One file edit; before is None when created, after is None when deleted."""
+
+    path: Path
+    before: str | None
+    after: str | None
+
+
+@dataclass(frozen=True, slots=True)
+class HookSpec:
+    """One hook an adapter wires: the agent event, its command and whether the agent waits."""
+
+    event: str
+    command: str
+    timeout_s: int
+    waits: bool
+
+
+class AgentAdapter(Protocol):
+    """Writes and removes one agent's config; the only place agent specifics live."""
+
+    name: str
+
+    def detect(self, root: Path) -> bool: ...
+
+    def install(self, root: Path, opts: InstallOpts) -> list[FileChange]: ...
+
+    def uninstall(self, root: Path, opts: InstallOpts) -> list[FileChange]: ...
+
+    def hook_events(self) -> Mapping[str, HookSpec]: ...
+
+
+type AdapterRegistry = Registry[str, AgentAdapter]
+
+
+class AgentConfigError(Exception):
+    """An agent config file that cannot be merged safely."""
+
+    def __init__(self, path: Path, message: str) -> None:
+        super().__init__(f"{path}: {message}")
+        self.path = path
+
+
+def read_exact(path: Path) -> str | None:
+    """Read a file as utf-8 without newline translation; None when absent."""
+    try:
+        return path.read_bytes().decode("utf-8")
+    except FileNotFoundError:
+        return None
+    except UnicodeDecodeError as exc:
+        raise AgentConfigError(path, f"not valid utf-8: {exc.reason}") from exc
+
+
+def _prune_empty_dirs(start: Path, stop: Path) -> None:
+    for directory in (start, *start.parents):
+        if directory == stop or stop not in directory.parents:
+            return
+        try:
+            directory.rmdir()
+        except OSError:
+            return
+
+
+def apply_changes(changes: list[FileChange], stop: Path) -> None:
+    """Write or delete every changed file; emptied directories below stop are removed."""
+    for change in changes:
+        if change.after is None:
+            change.path.unlink(missing_ok=True)
+            _prune_empty_dirs(change.path.parent, stop)
+        else:
+            change.path.parent.mkdir(parents=True, exist_ok=True)
+            change.path.write_bytes(change.after.encode("utf-8"))
+
+
+def plan_change(path: Path, after: str | None) -> FileChange | None:
+    """Build a FileChange against the file's current content; None when nothing changes."""
+    before = read_exact(path)
+    if after is not None and before is not None:
+        after = _match_line_endings(before, after)
+    if before == after:
+        return None
+    return FileChange(path, before, after)
+
+
+def _match_line_endings(before: str, after: str) -> str:
+    """Write CRLF back to a file that used CRLF, so a Windows user's file round-trips."""
+    if "\r\n" not in before or "\r\n" in after:
+        return after
+    return after.replace("\n", "\r\n")

contextweave/agents/blocks.py

@@ -0,0 +1,59 @@
+import re
+from dataclasses import dataclass
+
+BEGIN = re.compile(r"<!-- contextweave:begin v=(\d+) -->")
+END = "<!-- contextweave:end -->"
+
+
+@dataclass(frozen=True, slots=True)
+class BlockSpan:
+    """Byte-exact location of a marked block: begin marker start to end marker end."""
+
+    start: int
+    end: int
+    version: int
+
+
+def find_block(text: str) -> BlockSpan | None:
+    """Locate the first begin marker and the end marker that follows it."""
+    begin = BEGIN.search(text)
+    if begin is None:
+        return None
+    end = text.find(END, begin.end())
+    if end < 0:
+        return None
+    return BlockSpan(begin.start(), end + len(END), int(begin.group(1)))
+
+
+def block_version(block: str) -> int:
+    """Version number declared by a block's begin marker."""
+    span = find_block(block)
+    if span is None:
+        raise ValueError("block has no markers")
+    return span.version
+
+
+def upsert_block(text: str, block: str) -> str:
+    """Replace the existing block in place, else append it after a blank line."""
+    span = find_block(text)
+    if span is not None:
+        return text[: span.start] + block + text[span.end :]
+    if not text:
+        return block + "\n"
+    separator = "\n" * (2 - min(2, len(text) - len(text.rstrip("\n"))))
+    return text + separator + block + "\n"
+
+
+def remove_block(text: str) -> str:
+    """Delete the block and its line break; a blank line before a block at the end goes too."""
+    span = find_block(text)
+    if span is None:
+        return text
+    start, end = span.start, span.end
+    if text.startswith("\r\n", end):
+        end += 2
+    elif text.startswith("\n", end):
+        end += 1
+    if end == len(text) and text.endswith("\n\n", 0, start):
+        start -= 1
+    return text[:start] + text[end:]

contextweave/agents/catalog.py

@@ -0,0 +1,17 @@
+from contextweave.agents.agents_md import AgentsMdAdapter
+from contextweave.agents.base import AdapterRegistry
+from contextweave.agents.claude_code import ClaudeCodeAdapter
+from contextweave.agents.codex import CodexAdapter
+from contextweave.core.registry import Registry
+
+DEFAULT_AGENT = "claude_code"
+NO_AGENT = "none"
+
+
+def default_adapters() -> AdapterRegistry:
+    """A registry holding every shipped adapter, one row each (V10)."""
+    registry: AdapterRegistry = Registry()
+    registry.register(ClaudeCodeAdapter.name, ClaudeCodeAdapter())
+    registry.register(AgentsMdAdapter.name, AgentsMdAdapter())
+    registry.register(CodexAdapter.name, CodexAdapter())
+    return registry

contextweave/agents/claude_code/__init__.py

@@ -0,0 +1,3 @@
+from contextweave.agents.claude_code.adapter import ClaudeCodeAdapter
+
+__all__ = ["ClaudeCodeAdapter"]

contextweave/agents/claude_code/adapter.py

@@ -0,0 +1,123 @@
+from collections.abc import Mapping
+from pathlib import Path
+
+from contextweave.agents.base import (
+    FileChange,
+    HookSpec,
+    InstallOpts,
+    apply_changes,
+    plan_change,
+    read_exact,
+)
+from contextweave.agents.claude_code.files import (
+    hooks_document,
+    mcp_document,
+    merge_hooks,
+    merge_mcp,
+    plugin_manifest,
+    routing_skill,
+    unmerge_hooks,
+    unmerge_mcp,
+)
+from contextweave.agents.jsonio import Layout, dump_object
+from contextweave.agents.memory_block import plan_block_install, plan_block_removal
+from contextweave.index.root import STATE_DIR
+
+MCP_FILE = ".mcp.json"
+MEMORY_FILE = "CLAUDE.md"
+SETTINGS_FILE = Path(".claude") / "settings.json"
+PLUGIN_SUBDIR = Path(STATE_DIR) / "plugin"
+PLUGIN_MANIFEST = Path(".claude-plugin") / "plugin.json"
+PLUGIN_MCP = Path(MCP_FILE)
+PLUGIN_HOOKS = Path("hooks") / "hooks.json"
+PLUGIN_SKILL = Path("skills") / "contextweave-routing" / "SKILL.md"
+HOOK_EVENTS = ("SessionStart", "UserPromptSubmit", "PostToolUse", "Stop", "SessionEnd")
+WAITING_EVENTS = frozenset({"SessionStart"})
+HOOK_TIMEOUT_S = 1
+
+
+def _changes(candidates: list[FileChange | None]) -> list[FileChange]:
+    return [change for change in candidates if change is not None]
+
+
+class ClaudeCodeAdapter:
+    """Claude Code: .mcp.json, CLAUDE.md routing block, settings hooks, or a plugin directory."""
+
+    name = "claude_code"
+
+    def detect(self, root: Path) -> bool:
+        return any((root / marker).exists() for marker in (".claude", MEMORY_FILE, MCP_FILE))
+
+    def hook_events(self) -> Mapping[str, HookSpec]:
+        return {
+            event: HookSpec(event, f"cw hook {event}", HOOK_TIMEOUT_S, event in WAITING_EVENTS)
+            for event in HOOK_EVENTS
+        }
+
+    def install(self, root: Path, opts: InstallOpts) -> list[FileChange]:
+        changes = (
+            self._plan_plugin(self._plugin_dir(root, opts))
+            if opts.plugin
+            else self._plan_project(root)
+        )
+        if not opts.dry_run:
+            apply_changes(changes, root)
+        return changes
+
+    def uninstall(self, root: Path, opts: InstallOpts) -> list[FileChange]:
+        changes = [*self._plan_unproject(root), *self._plan_unplugin(self._plugin_dir(root, opts))]
+        if not opts.dry_run:
+            apply_changes(changes, root)
+        return changes
+
+    @staticmethod
+    def _plugin_dir(root: Path, opts: InstallOpts) -> Path:
+        return opts.plugin_dir if opts.plugin_dir is not None else root / PLUGIN_SUBDIR
+
+    def _plan_project(self, root: Path) -> list[FileChange]:
+        mcp_path = root / MCP_FILE
+        settings_path = root / SETTINGS_FILE
+        return _changes(
+            [
+                plan_change(mcp_path, merge_mcp(read_exact(mcp_path), mcp_path)),
+                plan_block_install(root / MEMORY_FILE),
+                plan_change(
+                    settings_path,
+                    merge_hooks(read_exact(settings_path), settings_path, self.hook_events()),
+                ),
+            ]
+        )
+
+    def _plan_unproject(self, root: Path) -> list[FileChange]:
+        mcp_path = root / MCP_FILE
+        settings_path = root / SETTINGS_FILE
+        mcp = read_exact(mcp_path)
+        settings = read_exact(settings_path)
+        return _changes(
+            [
+                plan_change(mcp_path, unmerge_mcp(mcp, mcp_path)) if mcp is not None else None,
+                plan_block_removal(root / MEMORY_FILE),
+                plan_change(
+                    settings_path, unmerge_hooks(settings, settings_path, self.hook_events())
+                )
+                if settings is not None
+                else None,
+            ]
+        )
+
+    def _plan_plugin(self, target: Path) -> list[FileChange]:
+        layout = Layout()
+        documents = {
+            PLUGIN_MANIFEST: dump_object(plugin_manifest(), layout),
+            PLUGIN_MCP: dump_object(mcp_document(), layout),
+            PLUGIN_HOOKS: dump_object(hooks_document(self.hook_events()), layout),
+            PLUGIN_SKILL: routing_skill(),
+        }
+        return _changes([plan_change(target / rel, text) for rel, text in documents.items()])
+
+    def _plan_unplugin(self, target: Path) -> list[FileChange]:
+        manifest = read_exact(target / PLUGIN_MANIFEST)
+        if manifest is None or '"contextweave"' not in manifest:
+            return []
+        paths = (PLUGIN_MANIFEST, PLUGIN_MCP, PLUGIN_HOOKS, PLUGIN_SKILL)
+        return _changes([plan_change(target / rel, None) for rel in paths])

contextweave/agents/claude_code/files.py

@@ -0,0 +1,176 @@
+from collections.abc import Mapping
+from pathlib import Path
+
+from contextweave.agents.base import AgentConfigError, HookSpec
+from contextweave.agents.jsonio import (
+    JSONObject,
+    Layout,
+    detect_layout,
+    dump_object,
+    list_at,
+    object_at,
+    parse_object,
+)
+from contextweave.agents.routing import routing_block
+from contextweave.core.dist import package_version
+from contextweave.core.types import JSON
+
+SERVER_NAME = "contextweave"
+SERVER_ENTRY: JSONObject = {"command": "cw", "args": ["serve"]}
+
+
+def _load(text: str | None, path: Path) -> tuple[JSONObject, Layout]:
+    if text is None:
+        return {}, Layout()
+    return parse_object(text, path), detect_layout(text)
+
+
+def _finish(obj: JSONObject, layout: Layout) -> str | None:
+    return dump_object(obj, layout) if obj else None
+
+
+def _section(parent: JSONObject, key: str, path: Path) -> JSONObject | None:
+    section = object_at(parent, key)
+    if section is None and key in parent:
+        raise AgentConfigError(path, f"'{key}' must be a JSON object")
+    return section
+
+
+def merge_mcp(text: str | None, path: Path) -> str:
+    """Set mcpServers.contextweave, keeping every other key and its order."""
+    obj, layout = _load(text, path)
+    servers = _section(obj, "mcpServers", path)
+    if servers is not None and servers.get(SERVER_NAME) == SERVER_ENTRY:
+        return text if text is not None else dump_object(obj, layout)
+    if servers is None:
+        servers = {}
+        obj["mcpServers"] = servers
+    servers[SERVER_NAME] = dict(SERVER_ENTRY)
+    return dump_object(obj, layout)
+
+
+def unmerge_mcp(text: str, path: Path) -> str | None:
+    """Remove mcpServers.contextweave; None when nothing else remains."""
+    obj, layout = _load(text, path)
+    servers = _section(obj, "mcpServers", path)
+    if servers is None or SERVER_NAME not in servers:
+        return text
+    del servers[SERVER_NAME]
+    if not servers:
+        del obj["mcpServers"]
+    return _finish(obj, layout)
+
+
+def hook_entry(spec: HookSpec) -> JSONObject:
+    """The settings.json hook object for one spec."""
+    return {"type": "command", "command": spec.command, "timeout": spec.timeout_s}
+
+
+def _group_hooks(group: JSON) -> list[JSON] | None:
+    return list_at(group, "hooks") if isinstance(group, dict) else None
+
+
+def _has_command(group: JSON, command: str) -> bool:
+    entries = _group_hooks(group)
+    return entries is not None and any(
+        isinstance(entry, dict) and entry.get("command") == command for entry in entries
+    )
+
+
+def hooks_document(specs: Mapping[str, HookSpec]) -> JSONObject:
+    """A complete {hooks: ...} object for a plugin hooks.json."""
+    return {"hooks": {event: [{"hooks": [hook_entry(spec)]}] for event, spec in specs.items()}}
+
+
+def merge_hooks(text: str | None, path: Path, specs: Mapping[str, HookSpec]) -> str:
+    """Add our hook command under each event unless already present; user hooks untouched."""
+    obj, layout = _load(text, path)
+    hooks = _section(obj, "hooks", path)
+    if hooks is None:
+        hooks = {}
+        obj["hooks"] = hooks
+    changed = False
+    for event, spec in specs.items():
+        groups = list_at(hooks, event)
+        if groups is None and event in hooks:
+            raise AgentConfigError(path, f"hooks.{event} must be a JSON array")
+        if groups is None:
+            groups = []
+            hooks[event] = groups
+        if any(_has_command(group, spec.command) for group in groups):
+            continue
+        groups.append({"hooks": [hook_entry(spec)]})
+        changed = True
+    if not changed and text is not None:
+        return text
+    return dump_object(obj, layout)
+
+
+def _strip_commands(groups: list[JSON], commands: frozenset[str]) -> bool:
+    removed = False
+    for group in list(groups):
+        entries = _group_hooks(group)
+        if entries is None:
+            continue
+        kept = [
+            entry
+            for entry in entries
+            if not (isinstance(entry, dict) and entry.get("command") in commands)
+        ]
+        if len(kept) == len(entries):
+            continue
+        removed = True
+        if kept:
+            entries[:] = kept
+        else:
+            groups.remove(group)
+    return removed
+
+
+def unmerge_hooks(text: str, path: Path, specs: Mapping[str, HookSpec]) -> str | None:
+    """Remove only our hook commands, dropping groups, events and hooks that become empty."""
+    obj, layout = _load(text, path)
+    hooks = _section(obj, "hooks", path)
+    if hooks is None:
+        return text
+    commands = frozenset(spec.command for spec in specs.values())
+    removed = False
+    for event in list(hooks):
+        groups = list_at(hooks, event)
+        if groups is None or not _strip_commands(groups, commands):
+            continue
+        removed = True
+        if not groups:
+            del hooks[event]
+    if not removed:
+        return text
+    if not hooks:
+        del obj["hooks"]
+    return _finish(obj, layout)
+
+
+def plugin_manifest() -> JSONObject:
+    """The .claude-plugin/plugin.json document."""
+    return {
+        "name": SERVER_NAME,
+        "version": package_version(),
+        "description": "ContextWeave code retrieval and session memory",
+    }
+
+
+def mcp_document() -> JSONObject:
+    """A complete .mcp.json object registering the server."""
+    return {"mcpServers": {SERVER_NAME: dict(SERVER_ENTRY)}}
+
+
+def routing_skill() -> str:
+    """The plugin's routing skill: frontmatter plus the routing block without its markers."""
+    body = "\n".join(routing_block().splitlines()[1:-1])
+    return (
+        "---\n"
+        f"name: {SERVER_NAME}-routing\n"
+        "description: Route code questions to ContextWeave tools: get_symbol, search_symbols, "
+        "file_outline for named things, context_search for described behaviour. Use when "
+        "exploring or answering questions about code.\n"
+        "---\n\n" + body + "\n"
+    )