claude-code-capabilities 0.1.2__py3-none-any.whl

capdisc/__init__.py

@@ -0,0 +1,69 @@
+"""Discovery of Claude Code capabilities: skills, agents, plugins, MCP servers, hooks.
+
+Scans the environment's scope roots into a typed inventory, harvests plugin and MCP
+metadata, and assembles capability catalogs and the environment report.
+"""
+
+from __future__ import annotations
+
+from .catalog import (
+    Catalog,
+    CatalogEntry,
+    CatalogMcpServer,
+    CatalogPlugin,
+    CatalogSkill,
+    CatalogTool,
+    McpTool,
+)
+from .discovery import BUILTIN_TOOLS, scan_environment, scan_indexed_skills, scan_skills
+from .mcp_catalog import enumerate_mcp_servers
+from .mcp_harvest import (
+    cache_is_stale,
+    read_mcp_cache,
+    refresh_in_background,
+    refresh_mcp_cache,
+    write_mcp_cache,
+)
+from .plugin_catalog import (
+    enumerate_plugins,
+    enumerate_plugins_with_paths,
+    installed_plugin_dirs,
+    installed_plugins,
+)
+from .report import EnvironmentReport, build_report, write_report, write_report_on_start
+from .scope import ScopeInventory, ScopeRoots, default_managed_dir
+from .settings import DiscoverySettings, ExtraSourceDir, get_settings
+
+__all__ = [
+    "BUILTIN_TOOLS",
+    "Catalog",
+    "CatalogEntry",
+    "CatalogMcpServer",
+    "CatalogPlugin",
+    "CatalogSkill",
+    "CatalogTool",
+    "DiscoverySettings",
+    "EnvironmentReport",
+    "ExtraSourceDir",
+    "McpTool",
+    "ScopeInventory",
+    "ScopeRoots",
+    "build_report",
+    "cache_is_stale",
+    "default_managed_dir",
+    "enumerate_mcp_servers",
+    "enumerate_plugins",
+    "enumerate_plugins_with_paths",
+    "get_settings",
+    "installed_plugin_dirs",
+    "installed_plugins",
+    "read_mcp_cache",
+    "refresh_in_background",
+    "refresh_mcp_cache",
+    "scan_environment",
+    "scan_indexed_skills",
+    "scan_skills",
+    "write_mcp_cache",
+    "write_report",
+    "write_report_on_start",
+]

capdisc/base.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+
+import re
+
+from pydantic import BaseModel, ConfigDict
+from pydantic.alias_generators import to_camel
+from pydantic.fields import ComputedFieldInfo, FieldInfo
+
+_CAMEL_BOUNDARY = re.compile(r"(?<=[a-z0-9])(?=[A-Z])")
+
+
+def humanize_field_title(field_name: str, _info: FieldInfo | ComputedFieldInfo) -> str:
+    """A clean, alias-independent JSON-Schema title from a field's Python name.
+
+    Splits snake_case, kebab-case, and camelCase into words and renders them sentence-cased
+    (`status_message` -> `Status message`). Avoids the mangled titles Pydantic derives from a
+    camelCase/hyphenated alias when a schema is exported `by_alias` (`statusMessage` -> the broken
+    `Statusmessage`). Set as `field_title_generator`, so it drives the field-level `title` only;
+    a domain-primitive alias's own `title` on the inner type is untouched.
+    """
+    spaced = _CAMEL_BOUNDARY.sub(" ", field_name.replace("_", " ").replace("-", " "))
+    return " ".join(spaced.split()).capitalize()
+
+
+class FrozenModel(BaseModel):
+    """Immutable, strict domain model — the single config preset for this package."""
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+
+class FrozenWireModel(BaseModel):
+    """Immutable model whose snake_case fields bind to the camelCase JSON keys of a Claude Code
+    config file — accepts either spelling on load, emits camelCase on dump. Tolerant of unknown
+    keys (`extra="ignore"`): this is the ingest boundary for config written by a Claude Code that
+    may be newer than us, so a field we don't model yet is dropped, never a parse failure."""
+
+    model_config = ConfigDict(
+        extra="ignore",
+        frozen=True,
+        alias_generator=to_camel,
+        populate_by_name=True,
+        serialize_by_alias=True,
+        field_title_generator=humanize_field_title,
+    )
+
+
+class MutableModel(BaseModel):
+    """Strict but mutable domain model — for in-place accumulators that fill across a loop."""
+
+    model_config = ConfigDict(extra="forbid")
+
+
+class InputModel(BaseModel):
+    """Lenient boundary model — ignores unknown keys from external sources."""
+
+    model_config = ConfigDict(extra="ignore")

capdisc/catalog/__init__.py

@@ -0,0 +1,71 @@
+from __future__ import annotations
+
+from .entries import (
+    Catalog,
+    CatalogEntry,
+    CatalogMcpServer,
+    CatalogPlugin,
+    CatalogSkill,
+    CatalogTool,
+    McpTool,
+)
+from .types import (
+    CATALOG_ID_MAX,
+    DEFAULT_RECALL_LIMIT,
+    DESCRIPTION_TOKEN_MAX,
+    MCP_INPUT_SCHEMA_MAX_BYTES,
+    MCP_TOOL_DESCRIPTION_MAX,
+    MCP_TOOL_PARAMS_MAX,
+    RELEVANCE_THRESHOLD,
+    BuiltinTool,
+    CatalogEntryId,
+    CatalogIdPrefix,
+    EntryDescription,
+    McpInputSchema,
+    McpServerRef,
+    McpToolCount,
+    McpToolName,
+    NeedsNetworkFlag,
+    PluginRef,
+    ReadOnlyFlag,
+    RecallLimit,
+    RelevanceScore,
+    SkillRef,
+    Tag,
+    ToolRef,
+    catalog_id,
+)
+
+__all__ = [
+    "CATALOG_ID_MAX",
+    "DEFAULT_RECALL_LIMIT",
+    "DESCRIPTION_TOKEN_MAX",
+    "MCP_INPUT_SCHEMA_MAX_BYTES",
+    "MCP_TOOL_DESCRIPTION_MAX",
+    "MCP_TOOL_PARAMS_MAX",
+    "RELEVANCE_THRESHOLD",
+    "BuiltinTool",
+    "Catalog",
+    "CatalogEntry",
+    "CatalogEntryId",
+    "CatalogIdPrefix",
+    "CatalogMcpServer",
+    "CatalogPlugin",
+    "CatalogSkill",
+    "CatalogTool",
+    "EntryDescription",
+    "McpInputSchema",
+    "McpServerRef",
+    "McpTool",
+    "McpToolCount",
+    "McpToolName",
+    "NeedsNetworkFlag",
+    "PluginRef",
+    "ReadOnlyFlag",
+    "RecallLimit",
+    "RelevanceScore",
+    "SkillRef",
+    "Tag",
+    "ToolRef",
+    "catalog_id",
+]

capdisc/catalog/entries.py

@@ -0,0 +1,104 @@
+from __future__ import annotations
+
+from typing import Annotated, Literal
+
+from pydantic import Field
+
+from ..base import FrozenModel
+from .types import (
+    MCP_TOOL_PARAMS_MAX,
+    CatalogEntryId,
+    EntryDescription,
+    McpInputSchema,
+    McpServerRef,
+    McpToolDescription,
+    McpToolName,
+    NeedsNetworkFlag,
+    PluginRef,
+    ReadOnlyFlag,
+    SkillRef,
+    Tag,
+    ToolRef,
+)
+
+
+class _Card(FrozenModel):
+    """Fields every catalog entry shares: its id, description, and recall tags."""
+
+    id: CatalogEntryId
+    description: EntryDescription
+    tags: list[Tag] = []
+
+    @property
+    def search_text(self) -> str:
+        """The text recall ranks this entry on — its description and tags."""
+        return " ".join((self.description, *self.tags))
+
+
+class McpTool(FrozenModel):
+    """One tool a connected MCP server provides, harvested from its `list_tools()`: its name,
+    input-parameter names, full input schema, and description — the content that lets recall
+    rank a server by what its tools actually do, not just its name."""
+
+    name: McpToolName
+    description: McpToolDescription = ""
+    params: list[McpToolName] = Field(default_factory=list, max_length=MCP_TOOL_PARAMS_MAX)
+    input_schema: McpInputSchema | None = None
+
+
+class _Tool(_Card):
+    """Shared execution-constraint facets (`read_only`, `needs_network`) for tool-like entries."""
+
+    ref: ToolRef
+    read_only: ReadOnlyFlag = True
+    needs_network: NeedsNetworkFlag = False
+
+
+class CatalogSkill(_Card):
+    """A skill an agent can load."""
+
+    kind: Literal["skill"] = "skill"
+    ref: SkillRef
+
+
+class CatalogTool(_Tool):
+    """A built-in tool an agent can be granted, with its execution-constraint facets."""
+
+    kind: Literal["tool"] = "tool"
+
+
+class CatalogMcpServer(_Card):
+    """A connected MCP server an agent can be wired to, with its harvested tools."""
+
+    kind: Literal["mcp_server"] = "mcp_server"
+    ref: McpServerRef
+    tools: list[McpTool] = []
+
+    @property
+    def search_text(self) -> str:
+        """The server's own description/tags plus each harvested tool's name, parameters, and
+        description — so a task matches what the server's tools do, fixing name-only ranking."""
+        tools = " ".join(f"{t.name} {' '.join(t.params)} {t.description}" for t in self.tools)
+        return f"{super().search_text} {tools}".strip()
+
+
+class CatalogPlugin(_Card):
+    """An installed plugin an agent can draw from, with the skills and MCP servers it bundles."""
+
+    kind: Literal["plugin"] = "plugin"
+    ref: PluginRef
+    skills: list[SkillRef] = []
+    mcp_servers: list[McpServerRef] = []
+
+
+CatalogEntry = Annotated[
+    CatalogSkill | CatalogTool | CatalogMcpServer | CatalogPlugin,
+    Field(discriminator="kind"),
+]
+
+
+class Catalog(FrozenModel):
+    """The full set of capabilities — skills, tools, MCP servers, and plugins — the generator
+    can draw from when building an agent."""
+
+    entries: list[CatalogEntry]

capdisc/catalog/types.py

@@ -0,0 +1,227 @@
+from __future__ import annotations
+
+import re
+from enum import StrEnum
+from typing import Annotated, Literal
+
+from pydantic import Field, JsonValue, TypeAdapter
+from pydantic.functional_validators import AfterValidator, BeforeValidator
+
+from ..tokens import token_bounds
+
+DESCRIPTION_TOKEN_MAX = 512
+CATALOG_ID_MAX = 64  # length cap of CatalogEntryId; catalog_id truncates to it
+MCP_TOOL_DESCRIPTION_MAX = 4000  # length cap of McpToolDescription; harvest truncates to it
+MCP_TOOL_PARAMS_MAX = 200  # item cap of McpTool.params
+MCP_INPUT_SCHEMA_MAX_BYTES = 20_000  # serialized size cap of McpInputSchema
+
+_INPUT_SCHEMA_ADAPTER: TypeAdapter[dict[str, JsonValue]] = TypeAdapter(dict[str, JsonValue])
+
+_SLUG_SKILL = re.compile(r"[^a-z0-9:-]+")  # skill refs keep ':' for plugin:skill
+_SLUG_REF = re.compile(r"[^a-z0-9_-]+")  # server and plugin refs keep '_'
+_SLUG_ID = re.compile(r"[^a-z0-9._-]+")  # catalog ids keep '.' for the 'kind.ref' shape
+
+
+def _slugify(value: str, disallowed: re.Pattern[str], max_len: int) -> str:
+    """Normalize an arbitrary name into a ref: lowercase, collapse disallowed runs to '-', trim
+    edge punctuation so it starts and ends on a word char, and truncate."""
+    return disallowed.sub("-", value.strip().lower()).strip("-:_")[:max_len]
+
+
+def _to_skill_ref(value: str) -> str:
+    """Slugify a name into a `SkillRef`, keeping `:` for the `plugin:skill` form (max 128)."""
+    return _slugify(value, _SLUG_SKILL, 128)
+
+
+def _to_underscore_ref(value: str) -> str:
+    """Slugify a name into a server/plugin ref, keeping `_` (max 64)."""
+    return _slugify(value, _SLUG_REF, 64)
+
+
+CatalogIdPrefix = Literal["plugin", "mcp", "skill"]
+
+
+def catalog_id(prefix: CatalogIdPrefix, ref: str) -> CatalogEntryId:
+    """A valid `CatalogEntryId` for `prefix.ref` — folds ':' and overflow away so a valid ref
+    never yields an unrepresentable id. `CatalogEntryId` itself stays strict (it is a lookup
+    key); this is the one place a kind+ref is composed into an id."""
+    return _slugify(f"{prefix}.{ref}", _SLUG_ID, CATALOG_ID_MAX)
+
+
+class BuiltinTool(StrEnum):
+    """The grant refs of the built-in Claude Code tools — the single source for both the tool
+    catalog cards and the default tool set a generated agent receives."""
+
+    read = "Read"
+    write = "Write"
+    edit = "Edit"
+    glob = "Glob"
+    grep = "Grep"
+    bash = "Bash"
+    web_fetch = "WebFetch"
+    web_search = "WebSearch"
+    task = "Task"
+
+
+EntryDescription = Annotated[
+    str,
+    Field(
+        min_length=8,
+        max_length=1536,
+        title="Entry description",
+        description="What a catalog entry provides and when it applies.",
+        examples=["Reads a file from disk."],
+    ),
+    token_bounds(DESCRIPTION_TOKEN_MAX),
+]
+ToolRef = Annotated[
+    str,
+    Field(
+        min_length=1,
+        max_length=200,
+        title="Tool ref",
+        description="A tool grant string, e.g. 'Read', 'Bash(git log:*)', or 'mcp__server__tool'.",
+        examples=["Read", "Bash(git log:*)"],
+    ),
+]
+McpToolName = Annotated[
+    str,
+    Field(
+        pattern=r"^[A-Za-z0-9][A-Za-z0-9_.-]{0,127}$",
+        title="MCP tool name",
+        description="Name of a tool (or input parameter) provided by an MCP server.",
+        examples=["browser_navigate", "file_path"],
+    ),
+]
+McpToolDescription = Annotated[
+    str,
+    Field(
+        max_length=MCP_TOOL_DESCRIPTION_MAX,
+        title="MCP tool description",
+        description="What an MCP tool does, as reported by the server's `list_tools()`.",
+        examples=["Navigate the browser to a url and wait for load."],
+    ),
+]
+
+
+def _check_schema_size(value: dict[str, JsonValue]) -> dict[str, JsonValue]:
+    """Reject a schema whose JSON serialization exceeds `MCP_INPUT_SCHEMA_MAX_BYTES` — an MCP
+    server's `list_tools()` response is untrusted input, and one tool's input schema must not be
+    able to inflate the on-disk cache without limit."""
+    if len(_INPUT_SCHEMA_ADAPTER.dump_json(value)) > MCP_INPUT_SCHEMA_MAX_BYTES:
+        raise ValueError(f"input schema exceeds {MCP_INPUT_SCHEMA_MAX_BYTES} bytes serialized")
+    return value
+
+
+McpInputSchema = Annotated[
+    dict[str, JsonValue],
+    AfterValidator(_check_schema_size),
+    Field(
+        title="MCP tool input schema",
+        description=(
+            "Full JSON Schema object for an MCP tool's input, as reported by `list_tools()`."
+        ),
+        examples=[
+            {
+                "type": "object",
+                "properties": {"url": {"type": "string"}},
+                "required": ["url"],
+            }
+        ],
+    ),
+]
+SkillRef = Annotated[
+    str,
+    BeforeValidator(_to_skill_ref),
+    Field(
+        pattern=r"^[a-z0-9][a-z0-9:-]{0,127}$",
+        title="Skill ref",
+        description="A skill name or plugin:skill reference; a raw name is slugified to one.",
+        examples=["error-handling", "my-plugin:my-skill"],
+    ),
+]
+McpServerRef = Annotated[
+    str,
+    BeforeValidator(_to_underscore_ref),
+    Field(
+        pattern=r"^[a-z0-9][a-z0-9_-]{0,63}$",
+        title="MCP server",
+        description="An MCP server name; a raw name is slugified to one.",
+        examples=["playwright"],
+    ),
+]
+PluginRef = Annotated[
+    str,
+    BeforeValidator(_to_underscore_ref),
+    Field(
+        pattern=r"^[a-z0-9][a-z0-9_-]{0,63}$",
+        title="Plugin",
+        description="An installed plugin name (marketplace suffix stripped); slugified.",
+        examples=["agentforge"],
+    ),
+]
+Tag = Annotated[
+    str,
+    Field(
+        pattern=r"^[a-z0-9][a-z0-9-]{0,31}$",
+        title="Tag",
+        description="A keyword folded into a catalog entry's text for lexical recall.",
+        examples=["git"],
+    ),
+]
+CatalogEntryId = Annotated[
+    str,
+    Field(
+        pattern=r"^[a-z0-9][a-z0-9._-]{0,63}$",
+        title="Catalog id",
+        description=(
+            "Stable id of one item in the catalog of skills, tools, and MCP servers an agent "
+            "can be built from. Strict — it is a lookup key; compose ids via catalog_id()."
+        ),
+        examples=["tool.read"],
+    ),
+]
+RelevanceScore = Annotated[
+    float,
+    Field(
+        ge=0.0,
+        le=1.0,
+        title="Relevance",
+        description="How well a catalog item matches the task, from 0 (no match) to 1 (best).",
+    ),
+]
+RecallLimit = Annotated[
+    int,
+    Field(
+        ge=1,
+        le=200,
+        title="Recall limit",
+        description="Most matching catalog items the search step may return.",
+    ),
+]
+McpToolCount = Annotated[
+    int,
+    Field(
+        ge=0,
+        title="MCP tool count",
+        description="Number of tools a connected MCP server provides.",
+        examples=[4],
+    ),
+]
+ReadOnlyFlag = Annotated[
+    bool,
+    Field(
+        title="Read-only",
+        description="Whether the tool only reads state, never writes or executes.",
+    ),
+]
+NeedsNetworkFlag = Annotated[
+    bool,
+    Field(
+        title="Needs network",
+        description="Whether the tool requires outbound network access to function.",
+    ),
+]
+
+DEFAULT_RECALL_LIMIT = 30
+RELEVANCE_THRESHOLD = 0.1