mcp-server-pixeltable-developer 0.2.1__py3-none-any.whl

mcp_server_pixeltable_developer/models.py

@@ -0,0 +1,192 @@
+"""Typed MCP inputs and outputs."""
+
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from pydantic import BaseModel, ConfigDict, Field, JsonValue
+
+
+class StrictModel(BaseModel):
+    """Base model for stable public result contracts."""
+
+    model_config = ConfigDict(extra="forbid")
+
+
+class CatalogEntry(BaseModel):
+    """One object in the Pixeltable catalog tree."""
+
+    model_config = ConfigDict(extra="allow")
+
+    name: str | None = None
+    path: str
+    kind: str | None = None
+    rows: int | None = None
+    columns: int | None = None
+    version: int | None = None
+    error_count: int | None = None
+    base: str | None = None
+    entries: list[CatalogEntry] = Field(default_factory=list)
+
+
+class CatalogResult(StrictModel):
+    """Catalog entries below a requested path."""
+
+    path: str
+    entries: list[CatalogEntry]
+    tree: CatalogEntry | None = None
+
+
+class ColumnDescription(BaseModel):
+    """Relevant metadata for a table column."""
+
+    model_config = ConfigDict(extra="allow")
+
+    name: str
+    type_: str
+    is_stored: bool | None = None
+    is_primary_key: bool | None = None
+    is_computed: bool | None = None
+    computed_with: str | None = None
+    depends_on: list[list[str]] | None = None
+    comment: str | None = None
+
+
+class TableDescription(BaseModel):
+    """Schema and metadata reported by ``pxt describe``."""
+
+    model_config = ConfigDict(extra="allow")
+
+    id: str
+    name: str
+    path: str
+    kind: str
+    columns: dict[str, ColumnDescription]
+    indexes: dict[str, Any] = Field(default_factory=dict)
+    has_default_idxs: bool = False
+    is_view: bool = False
+    is_snapshot: bool = False
+    version: int
+    primary_key: list[str] | str | None = None
+
+
+class RowsResult(StrictModel):
+    """A bounded table preview."""
+
+    path: str
+    rows: list[dict[str, JsonValue]]
+    count: int
+
+
+class RowResult(StrictModel):
+    """One row selected by primary key."""
+
+    path: str
+    row: dict[str, JsonValue]
+
+
+class ErrorsResult(StrictModel):
+    """Failed computed-column values for a table."""
+
+    path: str
+    column: str | None = None
+    errors: list[dict[str, JsonValue]]
+    count: int
+
+
+class InsertResult(StrictModel):
+    """Pixeltable insertion statistics."""
+
+    path: str
+    num_rows: int
+    num_computed_values: int
+    num_exceptions: int
+    columns_with_exceptions: list[str]
+    updated_columns: list[str]
+
+
+class CheckResult(StrictModel):
+    """Static validation result for a schema or service file."""
+
+    kind: Literal["schema", "service"]
+    file: str
+    valid: bool
+    errors: list[str]
+    warnings: list[str]
+
+
+class ReconcileResult(StrictModel):
+    """A schema or service reconciliation result."""
+
+    kind: Literal["schema", "service"]
+    operation: Literal["diff", "update", "prune"]
+    file: str
+    target: str
+    pending: bool
+    details: JsonValue
+
+
+class ServiceInfo(BaseModel):
+    """Stable service fields with forward-compatible CLI metadata."""
+
+    model_config = ConfigDict(extra="allow")
+
+    name: str
+    catalog_path: str | None = None
+    endpoint: str | None = None
+    port: int | None = Field(default=None, ge=1, le=65535)
+    state: str | None = None
+    error: str | None = None
+    app_module: str | None = None
+    spec: JsonValue = None
+    pid: int | None = None
+    process_started_at: float | None = None
+
+
+class ServiceListResult(StrictModel):
+    """Services known to the Pixeltable daemon."""
+
+    target: str | None = None
+    services: list[ServiceInfo]
+
+
+class ServiceStopResult(StrictModel):
+    """Services stopped by a request."""
+
+    names: list[str]
+    details: JsonValue
+
+
+class ScaffoldResult(StrictModel):
+    """A newly generated application or schema file."""
+
+    project: str
+    kind: Literal["service", "schema"]
+    file: str
+    created: bool
+
+
+class RecomputeResult(StrictModel):
+    """A computed-column recovery plan or execution result."""
+
+    path: str
+    columns: list[str]
+    errors_only: bool
+    dry_run: bool
+    pending: bool
+    details: JsonValue
+
+
+class StatusResource(StrictModel):
+    """Redacted server and runtime status."""
+
+    server_name: str
+    server_version: str
+    mcp_version: str
+    pixeltable_version: str
+    project: str
+    transport: str
+    unsafe_tools_enabled: bool
+
+
+JsonObject = dict[str, JsonValue]

mcp_server_pixeltable_developer/prompts.py

@@ -0,0 +1,97 @@
+"""Focused workflow prompts for Pixeltable application development."""
+
+from __future__ import annotations
+
+from typing import Annotated, Any
+
+from mcp.server.mcpserver import MCPServer
+from pydantic import Field
+
+
+def register_prompts(server: MCPServer[Any]) -> None:
+    """Register the four supported workflow prompts."""
+
+    @server.prompt(
+        name="pixeltable_build_app",
+        title="Build a Pixeltable application",
+        description="Plan and implement one app.py with TableModel tables and FastAPIRouter routes.",
+    )
+    def build_app(
+        goal: Annotated[str, Field(min_length=1, description="What the application should do.")],
+    ) -> str:
+        return f"""Build a Pixeltable application for this goal:
+
+{goal}
+
+Read pixeltable://guidance/app first. Work in one source-controlled application file.
+Start from `pxt init` and `pxt service example --out app.py`; declare stored columns
+with annotations, computed columns with assignments, and HTTP routes with
+`FastAPIRouter` imported from `pixeltable.serving`. Validate, diff, and update in
+that order. Use deterministic local fixtures before adding provider calls."""
+
+    @server.prompt(
+        name="pixeltable_build_rag",
+        title="Build Pixeltable retrieval",
+        description="Design document or multimodal ingestion, chunking, embedding, and retrieval in Pixeltable.",
+    )
+    def build_rag(
+        source_media: Annotated[
+            str,
+            Field(min_length=1, description="Document, image, video, or audio inputs to ingest."),
+        ],
+        query_behavior: Annotated[
+            str,
+            Field(min_length=1, description="How callers should search and use the retrieved context."),
+        ],
+    ) -> str:
+        return f"""Build a Pixeltable retrieval application.
+
+Inputs: {source_media}
+Query behavior: {query_behavior}
+
+Use a TableModel application and Pixeltable computed columns. Use the appropriate
+document, image, video, or audio iterator; persist chunks in a view; add the
+modality-appropriate embedding index; and call similarity with a named modality
+argument. Keep the catalog as the system of record. Add a FastAPIRouter retrieval
+route, then validate, diff, update, insert deterministic fixtures, and test
+retrieval."""
+
+    @server.prompt(
+        name="pixeltable_build_agent",
+        title="Build a Pixeltable tool-calling agent",
+        description="Design an agent whose model responses and tool executions are persisted as computed columns.",
+    )
+    def build_agent(
+        objective: Annotated[str, Field(min_length=1, description="The agent's objective.")],
+        tools: Annotated[str, Field(min_length=1, description="The tools the model may call.")],
+    ) -> str:
+        return f"""Build a persistent Pixeltable tool-calling agent.
+
+Objective: {objective}
+Tools: {tools}
+
+Declare request, model response, tool-call, tool-result, and final-response columns
+in a TableModel application. Construct tool definitions with `pxt.tools()`, pass
+them to the provider function, and execute requested calls with `invoke_tools()`.
+Preserve provider outputs in their native type. Add an HTTP route, use mocked
+provider results for local wiring tests, and do not claim live-provider coverage."""
+
+    @server.prompt(
+        name="pixeltable_debug_computation",
+        title="Debug a Pixeltable computation",
+        description="Inspect failed computed values and build a bounded recovery procedure.",
+    )
+    def debug_computation(
+        table: Annotated[str, Field(min_length=1, description="Table or view path with failures.")],
+        column: Annotated[str, Field(min_length=1, description="Computed column to diagnose.")],
+    ) -> str:
+        return f"""Diagnose failures in `{table}.{column}`.
+
+Describe the table, list errors filtered to `{column}`, and inspect the input
+columns the expression depends on. Fix the source data, configuration, provider
+credentials, or application code that caused the error. Preview
+`pxt recompute {table} {column} --errors-only -n`; apply it with `-f` only after the
+preview is correct. If the fix changes the computed expression, apply it with a
+schema update, then recompute without `--errors-only`: the update keeps existing
+values. If the column's type must change, rename the column, because an in-place
+type change is unsupported."""

mcp_server_pixeltable_developer/resources.py

@@ -0,0 +1,134 @@
+"""Focused MCP resources for runtime context and Pixeltable guidance."""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+from typing import Any
+
+from mcp.server.mcpserver import MCPServer
+
+from . import __version__
+from .models import CatalogEntry, CatalogResult, StatusResource
+from .runtime import CommandRunner, ServerConfig
+
+APP_GUIDANCE = """# Pixeltable application workflow
+
+1. Run `pxt init` once in the project root.
+2. Start with `pxt service example --out app.py` (or `pxt schema example --brief --out schema.py`).
+3. Declare tables on `TableModel = pxt.model_base()`. Stored columns use annotations; computed columns use assignments.
+4. Import `FastAPIRouter` from `pixeltable.serving` and declare HTTP routes on it.
+   Keep tables, computed columns, and routes in the source-controlled application file.
+5. Validate with `pxt service check app.py`, inspect with
+   `pxt service diff app.py TARGET`, then apply with
+   `pxt service update app.py TARGET`.
+
+Stored columns are non-nullable by default. Write `pxt.String | None` when null is allowed. Do not use `pxt.Required`.
+Create computed columns declaratively. To change a computed expression, edit it and
+run `pxt schema update`: it records the new expression and keeps the stored values,
+so run `pxt recompute TABLE COLUMN -f` to refresh existing rows. Changing a column's
+type is UNSUPPORTED and applies nothing, even with `--allow-destructive`: rename a
+computed column instead, and declare a stored column `T | None` up front.
+Use Pixeltable iterators, embedding indexes, and `pxt.tools()` / `invoke_tools()`
+for multimodal retrieval and agents. Do not add a separate dataframe store or
+vector database.
+For failures, inspect `pxt errors TABLE` and preview
+`pxt recompute TABLE COLUMN --errors-only -n` before applying it with `-f`.
+
+Row-addressed operations (`pxt get`, `pxt errors`) require a primary key.
+`pxt service example` generates one: `id = pxt.Column(value=pxtf.uuid.uuid7(), primary_key=True)`,
+computed on insert. Declare a key in every model before its first schema update:
+Pixeltable cannot add a primary key to a table that already exists.
+"""
+
+
+CLOUD_GUIDANCE = """# Pixeltable Cloud preparation
+
+Cloud behavior in this server is source-reviewed but not live-tested. Review each diff before applying it.
+
+1. Sign in with `pxt login`, or export `PIXELTABLE_API_KEY`, which wins over a sign-in.
+2. Add `[[pixeltable.database]]` with `name = 'pxt://ORG:DATABASE'` to `pixeltable.toml`.
+3. Set provider keys with `pxt secret set pxt://ORG OPENAI_API_KEY=...`. Never put
+   secrets in `pixeltable.toml`: a database entry with a `secrets` mapping fails to load.
+4. Run `pxt db diff`, then `pxt db update pxt://ORG:DATABASE -f`. The first update creates the database.
+5. Run `pxt schema diff` and `pxt schema update` against the hosted target.
+6. Run `pxt service diff` and `pxt service update` only after the database code and schema are current.
+
+The MCP schema and service tools accept explicit `pxt://` targets. They never
+create databases or set secrets. A hosted `schema_update` or `service_update` call
+changes that hosted target, so inspect the corresponding diff first.
+"""
+
+
+def _distribution_version(name: str) -> str:
+    try:
+        return version(name)
+    except PackageNotFoundError:
+        return "not-installed"
+
+
+def register_resources(server: MCPServer[Any], config: ServerConfig, runner: CommandRunner) -> None:
+    """Register the four supported resources."""
+
+    @server.resource(
+        "pixeltable://status",
+        name="pixeltable_status",
+        title="Pixeltable MCP status",
+        description="Redacted server, package, project, and feature-mode versions.",
+        mime_type="application/json",
+    )
+    def status_resource() -> str:
+        status = StatusResource(
+            server_name="pixeltable-developer",
+            server_version=__version__,
+            mcp_version=_distribution_version("mcp"),
+            pixeltable_version=_distribution_version("pixeltable"),
+            project=config.project_root.name,
+            transport=config.transport,
+            unsafe_tools_enabled=config.unsafe_enabled,
+        )
+        return status.model_dump_json()
+
+    @server.resource(
+        "pixeltable://catalog",
+        name="pixeltable_catalog",
+        title="Pixeltable catalog",
+        description="Tables, views, and directories in the configured local catalog.",
+        mime_type="application/json",
+    )
+    async def catalog_resource() -> str:
+        result = await runner.pxt(["ls", "--tree", "--json"])
+        if not isinstance(result.data, dict):
+            raise RuntimeError("Pixeltable returned an unexpected catalog listing")
+        tree_payload = result.data.get("tree")
+        entries_payload = result.data.get("entries", [])
+        if isinstance(tree_payload, dict):
+            entries_payload = tree_payload.get("entries", entries_payload)
+        if not isinstance(entries_payload, list):
+            raise RuntimeError("Pixeltable returned an unexpected catalog listing")
+        tree = CatalogEntry.model_validate(tree_payload) if tree_payload is not None else None
+        catalog = CatalogResult(
+            path="",
+            entries=[CatalogEntry.model_validate(entry) for entry in entries_payload],
+            tree=tree,
+        )
+        return catalog.model_dump_json()
+
+    @server.resource(
+        "pixeltable://guidance/app",
+        name="pixeltable_application_guidance",
+        title="Pixeltable application guidance",
+        description="Application-first workflow aligned with Pixeltable 0.7.16 and skill 2.12.0.",
+        mime_type="text/markdown",
+    )
+    def application_guidance_resource() -> str:
+        return APP_GUIDANCE
+
+    @server.resource(
+        "pixeltable://guidance/cloud",
+        name="pixeltable_cloud_guidance",
+        title="Pixeltable Cloud preparation",
+        description="Reviewed deployment ordering and configuration guidance; not live-tested.",
+        mime_type="text/markdown",
+    )
+    def cloud_guidance_resource() -> str:
+        return CLOUD_GUIDANCE