deepquery-sdk 1.0.0__tar.gz → 1.1.1__tar.gz

{deepquery_sdk-1.0.0 → deepquery_sdk-1.1.1}/CHANGELOG.md

@@ -5,6 +5,33 @@ All notable changes to DeepQuerySDK are documented here. The SDK follows
 `Connector` class, the provenance envelope, or the manifest schema is a **major**
 bump and ships with an entry in [MIGRATIONS.md](MIGRATIONS.md).
 
+## [1.1.1] — 2026-06-08
+
+Patch — metadata/docs only, no code changes.
+
+### Fixed
+- Corrected the project URLs (Homepage / Repository / Changelog / Documentation)
+  to point at the real GitHub repository.
+
+## [1.1.0] — 2026-06-08
+
+Additive, backward-compatible. Connectors can now emit the other two MCP
+primitives alongside tools.
+
+### Added
+- `@mcp_resource` — declare URI-addressable **resources** (static `uri` or a
+  parameterized `uri_template`). Emitted via `resources/list`,
+  `resources/read`, and `resources/templates/list`; content is `str` or `bytes`.
+- `@prompt` — declare **prompt** templates (with arguments). Emitted via
+  `prompts/list` and `prompts/get`; the handler returns a string or a list of
+  `{role, text}` messages.
+- Manifest now carries `mcp_resources` and `prompts`; `validate` checks their
+  descriptions (present + injection markers).
+
+Note: the existing `@resource` is unchanged — it declares a *read* and is emitted
+as a read-only **tool** (for parameterized search). `@mcp_resource` is the
+distinct MCP `resources` primitive.
+
 ## [1.0.0] — 2026-06-07
 
 First stable release. Establishes the SDK contract at **major version 1**:
@@ -40,4 +67,6 @@ connectors declaring `sdk_major_version = 1` are loadable by this runtime.
 - `scaffold` generates a complete, shippable connector project.
 - Published to PyPI as `deepquery-sdk`.
 
-[1.0.0]: https://github.com/GilbertAshivaka/deepquery-sdk/releases/tag/v1.0.0
+[1.1.1]: https://github.com/GilbertAshivaka/DeepQuerySDK/releases/tag/v1.1.1
+[1.1.0]: https://github.com/GilbertAshivaka/DeepQuerySDK/releases/tag/v1.1.0
+[1.0.0]: https://github.com/GilbertAshivaka/DeepQuerySDK/releases/tag/v1.0.0

{deepquery_sdk-1.0.0 → deepquery_sdk-1.1.1}/PKG-INFO

@@ -1,11 +1,11 @@
 Metadata-Version: 2.4
 Name: deepquery-sdk
-Version: 1.0.0
+Version: 1.1.1
 Summary: Connector Development Kit for Deep Query — build MCP-emitting connectors with built-in read/action safety classification and provenance.
-Project-URL: Homepage, https://github.com/GilbertAshivaka/deepquery-sdk
-Project-URL: Repository, https://github.com/GilbertAshivaka/deepquery-sdk
-Project-URL: Changelog, https://github.com/GilbertAshivaka/deepquery-sdk/blob/main/CHANGELOG.md
-Project-URL: Documentation, https://github.com/GilbertAshivaka/deepquery-sdk/blob/main/README.md
+Project-URL: Homepage, https://github.com/GilbertAshivaka/DeepQuerySDK
+Project-URL: Repository, https://github.com/GilbertAshivaka/DeepQuerySDK
+Project-URL: Changelog, https://github.com/GilbertAshivaka/DeepQuerySDK/blob/main/CHANGELOG.md
+Project-URL: Documentation, https://github.com/GilbertAshivaka/DeepQuerySDK/blob/main/README.md
 Author-email: Gilbert Ashivaka <gilbertashivaka@gmail.com>
 License: Apache-2.0
 License-File: LICENSE
@@ -35,7 +35,13 @@ standard [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server*
 — so Deep Query consumes it through the exact same interface as any public MCP
 server. You never touch JSON-RPC, transport, or schema plumbing.
 
-> **Status: v1.0.0 — all four build phases complete.** Core contracts (Phase 1),
+> **Status: v1.1.0 — connectors can now emit all three MCP primitives.**
+> Beyond tools (reads + gated actions), use `@mcp_resource` to expose
+> URI-addressable **resources** (static or templated) and `@prompt` to offer
+> **prompt** templates. See the **[Resources & Prompts guide](docs/resources-and-prompts.md)**
+> and [CHANGELOG.md](CHANGELOG.md). Built on v1.0.0 — all four build phases below remain.
+>
+> **v1.0.0 — all four build phases complete.** Core contracts (Phase 1),
 > the gated **preview → approve → execute / reject** lifecycle + OAuth 2.1 PKCE
 > scaffolding + credential injection (Phase 2), the `deepquery` **CLI** and
 > **mock-agent harness** with the §5/§6/§13 contracts encoded as `validate`

{deepquery_sdk-1.0.0 → deepquery_sdk-1.1.1}/README.md

@@ -5,7 +5,13 @@ standard [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server*
 — so Deep Query consumes it through the exact same interface as any public MCP
 server. You never touch JSON-RPC, transport, or schema plumbing.
 
-> **Status: v1.0.0 — all four build phases complete.** Core contracts (Phase 1),
+> **Status: v1.1.0 — connectors can now emit all three MCP primitives.**
+> Beyond tools (reads + gated actions), use `@mcp_resource` to expose
+> URI-addressable **resources** (static or templated) and `@prompt` to offer
+> **prompt** templates. See the **[Resources & Prompts guide](docs/resources-and-prompts.md)**
+> and [CHANGELOG.md](CHANGELOG.md). Built on v1.0.0 — all four build phases below remain.
+>
+> **v1.0.0 — all four build phases complete.** Core contracts (Phase 1),
 > the gated **preview → approve → execute / reject** lifecycle + OAuth 2.1 PKCE
 > scaffolding + credential injection (Phase 2), the `deepquery` **CLI** and
 > **mock-agent harness** with the §5/§6/§13 contracts encoded as `validate`

deepquery_sdk-1.1.1/docs/resources-and-prompts.md

@@ -0,0 +1,202 @@
+# Resources & Prompts (DeepQuerySDK 1.1.0)
+
+This guide explains the two MCP primitives added in 1.1.0 — **resources** and
+**prompts** — in plain terms: what they are, when to reach for each, and how to
+add them to a connector. It assumes you've already built a basic connector
+(see the README quickstart).
+
+---
+
+## The big picture: three kinds of capability
+
+An MCP server (which is what your connector emits) can offer **three** kinds of
+thing. DeepQuerySDK now lets you declare all three:
+
+| You write | MCP primitive | What it's for | Emitted as |
+|---|---|---|---|
+| `@resource` | tool | A **search/fetch** the agent runs with parameters (e.g. "search tickets for X") | a read-only **tool** |
+| `@mcp_resource` | resource | A specific piece of data the agent pulls by its **address (URI)** (e.g. "the README", "article #42") | a **resource** |
+| `@action` | tool | An operation that **changes** something, gated behind human approval | a mutating **tool** |
+| `@prompt` | prompt | A reusable **prompt template** a person can pick (e.g. "summarize this ticket") | a **prompt** |
+
+> **The one thing to internalize:** `@resource` and `@mcp_resource` are *different*
+> despite the similar names.
+> - `@resource` = "the agent asks a question and you search" → it's a **tool**.
+> - `@mcp_resource` = "there's a thing at this URI, hand it over" → it's a **resource**.
+>
+> If your data is *looked up by parameters*, use `@resource`. If it's *addressed by
+> a stable URI*, use `@mcp_resource`.
+
+---
+
+## Resources: data addressed by a URI
+
+A resource is a piece of content that lives at a **URI** — like a file path or a
+web address, but it can use any scheme you like (`docs://`, `tickets://`, …).
+There are two flavours:
+
+### 1. Static resource — one fixed URI
+
+```python
+from deepquery_sdk import Connector, mcp_resource
+
+class DocsConnector(Connector):
+    name = "docs"
+    version = "1.0.0"
+
+    @mcp_resource(
+        uri="docs://readme",
+        name="README",
+        description="The project's README, in Markdown.",
+        mime_type="text/markdown",
+    )
+    def readme(self) -> str:
+        return "# My Project\n\nWelcome!"
+```
+
+That's it. The method **returns the content** as a string (text) or bytes (binary
+blob). The agent can now list this resource and read it by its URI `docs://readme`.
+
+### 2. Templated resource — a family of URIs with a parameter
+
+When you have *many* items of the same shape (articles, tickets, records), use a
+**URI template** with a `{placeholder}`. The placeholder becomes a method argument:
+
+```python
+    @mcp_resource(
+        uri_template="docs://article/{slug}",
+        name="Article",
+        description="A documentation article, addressed by its slug.",
+        mime_type="text/markdown",
+    )
+    def article(self, slug: str) -> str:
+        return load_article(slug)        # called with slug="getting-started" for docs://article/getting-started
+```
+
+The SDK matches an incoming URI like `docs://article/getting-started` against the
+template, pulls out `slug="getting-started"`, and calls your method with it.
+
+### What you get for free
+- The emitted server **advertises the `resources` capability** automatically (just
+  by having at least one `@mcp_resource`).
+- Resources show up in `resources/list` and (templates) `resources/templates/list`.
+- Reading a URI calls your method via `resources/read`.
+- **Deep Query cites resource content by its URI**, so anything an agent reads this
+  way stays a verifiable, timestamped source — just like a document chunk.
+
+### Content types
+- Return a **`str`** for text (set `mime_type` to something like `text/markdown`,
+  `application/json`, `text/plain` — default is `text/plain`).
+- Return **`bytes`** for binary content; it's base64-encoded automatically.
+
+---
+
+## Prompts: reusable templates a person picks
+
+A prompt is a **named template** your connector offers — think of it like a
+slash-command a user can choose ("Summarize a ticket", "Draft a reply"). Unlike
+tools, prompts are *user-controlled*: the host shows them to a person, who picks
+one and fills in any arguments.
+
+```python
+from deepquery_sdk import Connector, prompt
+
+class SupportConnector(Connector):
+    name = "support"
+    version = "1.0.0"
+
+    @prompt(
+        description="Draft a request to summarize a support ticket.",
+        arguments=[
+            {"name": "ticket_id", "description": "The ticket to summarize", "required": True},
+        ],
+    )
+    def summarize_ticket(self, ticket_id: str) -> str:
+        return f"Please summarize support ticket {ticket_id}, including its current status."
+```
+
+### Return shapes
+Your method returns either:
+- a **string** — becomes a single message from the user, or
+- a **list of messages** — `[{"role": "user", "text": "..."}, {"role": "assistant", "text": "..."}]`
+  — when you want a multi-turn template.
+
+### Arguments
+Declare them as a list. Each item is either:
+- a plain **name** (`["city", "state"]`), or
+- a **dict** with detail: `{"name": "ticket_id", "description": "...", "required": True}`.
+
+### A safety note
+Prompt text is **user/connector-provided content**, so Deep Query treats it as
+**untrusted** — it is never executed as instructions to the agent. You don't need
+to do anything special; just know your prompt text is data, not commands.
+
+---
+
+## A complete example
+
+```python
+from deepquery_sdk import Connector, resource, action, mcp_resource, prompt
+
+class HelpdeskConnector(Connector):
+    name = "helpdesk"
+    version = "1.0.0"
+    description = "Read and act on helpdesk tickets."
+
+    # A parameterized search -> emitted as a TOOL
+    @resource(description="Search tickets by text.",
+              input_schema={"type": "object", "properties": {"q": {"type": "string"}}, "required": ["q"]})
+    def search(self, q: str):
+        return [self.cite(t, source_object_id=t["id"], title_or_label=t["id"]) for t in find(q)]
+
+    # A specific ticket by URI -> emitted as a RESOURCE (template)
+    @mcp_resource(uri_template="helpdesk://ticket/{ticket_id}", name="Ticket",
+                  description="A single ticket by id.", mime_type="application/json")
+    def ticket(self, ticket_id: str) -> str:
+        return json.dumps(get_ticket(ticket_id))
+
+    # A user-pickable template -> emitted as a PROMPT
+    @prompt(description="Draft a reply to a ticket.",
+            arguments=[{"name": "ticket_id", "required": True}])
+    def draft_reply(self, ticket_id: str) -> str:
+        return f"Draft a polite reply to ticket {ticket_id}."
+
+    # A gated change -> emitted as a mutating TOOL (preview + execute)
+    @action(description="Close a ticket.",
+            input_schema={"type": "object", "properties": {"ticket_id": {"type": "string"}}, "required": ["ticket_id"]})
+    def close_ticket(self, ticket_id: str):
+        return close(ticket_id)
+
+    @close_ticket.preview
+    def _(self, ticket_id: str) -> str:
+        return f"Will close ticket {ticket_id}."
+```
+
+---
+
+## Validate before you ship
+
+`validate` now checks resource and prompt descriptions too (they must be present,
+and it flags text that looks like a prompt-injection instruction):
+
+```bash
+deepquery validate connector.py
+deepquery manifest connector.py     # shows resources + prompts in the manifest
+```
+
+---
+
+## FAQ
+
+**Do I have to add resources/prompts?** No. They're optional. A connector with only
+tools (reads + actions) is still complete.
+
+**`@resource` vs `@mcp_resource` again?** Parameter-driven lookup → `@resource`
+(tool). URI-addressed item → `@mcp_resource` (resource).
+
+**Is this a breaking change?** No — 1.1.0 is fully backward-compatible with 1.0.0
+connectors. Existing connectors keep working unchanged.
+
+**Does the connector advertise the capability only when I use it?** Yes. The server
+advertises `resources` only if you declare at least one `@mcp_resource`, and
+`prompts` only if you declare at least one `@prompt`.

{deepquery_sdk-1.0.0 → deepquery_sdk-1.1.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "deepquery-sdk"
-version = "1.0.0"
+version = "1.1.1"
 description = "Connector Development Kit for Deep Query — build MCP-emitting connectors with built-in read/action safety classification and provenance."
 readme = "README.md"
 requires-python = ">=3.10"
@@ -35,10 +35,10 @@ dev = ["pytest>=8", "pytest-asyncio>=0.25", "build>=1.2"]
 deepquery = "deepquery_sdk.cli.__main__:main"
 
 [project.urls]
-Homepage = "https://github.com/GilbertAshivaka/deepquery-sdk"
-Repository = "https://github.com/GilbertAshivaka/deepquery-sdk"
-Changelog = "https://github.com/GilbertAshivaka/deepquery-sdk/blob/main/CHANGELOG.md"
-Documentation = "https://github.com/GilbertAshivaka/deepquery-sdk/blob/main/README.md"
+Homepage = "https://github.com/GilbertAshivaka/DeepQuerySDK"
+Repository = "https://github.com/GilbertAshivaka/DeepQuerySDK"
+Changelog = "https://github.com/GilbertAshivaka/DeepQuerySDK/blob/main/CHANGELOG.md"
+Documentation = "https://github.com/GilbertAshivaka/DeepQuerySDK/blob/main/README.md"
 
 [tool.hatch.build.targets.wheel]
 packages = ["src/deepquery_sdk"]

{deepquery_sdk-1.0.0 → deepquery_sdk-1.1.1}/src/deepquery_sdk/__init__.py

@@ -42,10 +42,14 @@ from .manifest import (
     AuthMethod,
     DeploymentCompat,
     Manifest,
+    MCPResourceManifest,
+    PromptManifest,
     ResourceManifest,
     SDK_MAJOR_VERSION,
     SDK_VERSION,
 )
+from .mcp_resource import MCPResourceSpec, mcp_resource
+from .prompt import PromptArgumentSpec, PromptSpec, prompt
 from .provenance import CitedRecord, Provenance, make_provenance, now_iso
 from .resource import ResourceSpec, resource
 
@@ -58,6 +62,13 @@ __all__ = [
     "ResourceSpec",
     "action",
     "ActionSpec",
+    "mcp_resource",
+    "MCPResourceSpec",
+    "prompt",
+    "PromptSpec",
+    "PromptArgumentSpec",
+    "MCPResourceManifest",
+    "PromptManifest",
     "CapabilityKind",
     "CitedRecord",
     "Provenance",

{deepquery_sdk-1.0.0 → deepquery_sdk-1.1.1}/src/deepquery_sdk/connector.py

@@ -16,11 +16,15 @@ from typing import Any, Iterable, Iterator
 from .action import ActionSpec
 from .auth.base import AppliedAuth, AuthStrategy, Credential, CredentialError, CredentialProvider
 from .gate import ApprovalGate, PendingAction
+from .mcp_resource import MCPResourceSpec
+from .prompt import PromptArgumentSpec, PromptSpec
 from .manifest import (
     ActionManifest,
     AuthMethod,
     DeploymentCompat,
     Manifest,
+    MCPResourceManifest,
+    PromptManifest,
     ResourceManifest,
     SDK_MAJOR_VERSION,
 )
@@ -66,11 +70,15 @@ class Connector:
     # populated by __init_subclass__
     _resources: list[ResourceSpec]
     _actions: list[ActionSpec]
+    _mcp_resources: list[MCPResourceSpec]
+    _prompts: list[PromptSpec]
 
     def __init_subclass__(cls, **kwargs: Any) -> None:
         super().__init_subclass__(**kwargs)
         cls._resources = list(cls._collect_resources())
         cls._actions = list(cls._collect_actions())
+        cls._mcp_resources = list(cls._collect_mcp_resources())
+        cls._prompts = list(cls._collect_prompts())
         cls._validate_contracts()
 
     # -- collection -------------------------------------------------------
@@ -87,6 +95,34 @@ class Connector:
                     attr_name=attr_name,
                 )
 
+    @classmethod
+    def _collect_mcp_resources(cls) -> Iterable[MCPResourceSpec]:
+        for attr_name in dir(cls):
+            obj = getattr(cls, attr_name, None)
+            meta = getattr(obj, "__dq_mcp_resource__", None)
+            if meta is not None:
+                yield MCPResourceSpec(
+                    name=meta["name"],
+                    description=meta["description"],
+                    uri=meta["uri"],
+                    uri_template=meta["uri_template"],
+                    mime_type=meta["mime_type"],
+                    attr_name=attr_name,
+                )
+
+    @classmethod
+    def _collect_prompts(cls) -> Iterable[PromptSpec]:
+        for attr_name in dir(cls):
+            obj = getattr(cls, attr_name, None)
+            meta = getattr(obj, "__dq_prompt__", None)
+            if meta is not None:
+                yield PromptSpec(
+                    name=meta["name"],
+                    description=meta["description"],
+                    arguments=[PromptArgumentSpec(**a) for a in meta["arguments"]],
+                    attr_name=attr_name,
+                )
+
     @classmethod
     def _collect_actions(cls) -> Iterable[ActionSpec]:
         seen: set[int] = set()
@@ -229,6 +265,30 @@ class Connector:
     def actions(self) -> list[ActionSpec]:
         return type(self)._actions
 
+    @property
+    def mcp_resources(self) -> list[MCPResourceSpec]:
+        return type(self)._mcp_resources
+
+    @property
+    def prompts(self) -> list[PromptSpec]:
+        return type(self)._prompts
+
+    def read_mcp_resource(self, spec: MCPResourceSpec, params: dict[str, str]) -> str | bytes:
+        """Invoke an MCP resource's bound handler, returning its content."""
+        bound = getattr(self, spec.attr_name)
+        return bound(**params)
+
+    def render_prompt(self, spec: PromptSpec, arguments: dict[str, str]) -> list[dict[str, str]]:
+        """Invoke a prompt's handler and normalise to a list of {role, text}."""
+        bound = getattr(self, spec.attr_name)
+        result = bound(**(arguments or {}))
+        if isinstance(result, str):
+            return [{"role": "user", "text": result}]
+        messages: list[dict[str, str]] = []
+        for m in result:
+            messages.append({"role": m.get("role", "user"), "text": m.get("text", "")})
+        return messages
+
     def run_resource(self, spec: ResourceSpec, arguments: dict[str, Any]) -> list[CitedRecord]:
         """Invoke a resource's bound fetch method and normalise its output."""
         bound = getattr(self, spec.attr_name)
@@ -276,6 +336,17 @@ class Connector:
                 ActionManifest(name=s.name, description=s.description, has_preview=s.has_preview())
                 for s in self.actions
             ],
+            mcp_resources=[
+                MCPResourceManifest(
+                    name=s.name, description=s.description, address=s.address,
+                    is_template=s.is_template, mime_type=s.mime_type,
+                )
+                for s in self.mcp_resources
+            ],
+            prompts=[
+                PromptManifest(name=s.name, description=s.description, arguments=[a.name for a in s.arguments])
+                for s in self.prompts
+            ],
             deployment=DeploymentCompat(
                 requires_network=self.requires_network,
                 air_gapped_capable=self.air_gapped_capable,

{deepquery_sdk-1.0.0 → deepquery_sdk-1.1.1}/src/deepquery_sdk/manifest.py

@@ -17,7 +17,7 @@ from pydantic import BaseModel, Field
 # Single source of truth for the SDK's version. The package version in
 # pyproject.toml must match SDK_VERSION (guarded by a test). The contract major
 # version — what a connector manifest targets — is the major of SDK_VERSION.
-SDK_VERSION = "1.0.0"
+SDK_VERSION = "1.1.1"
 SDK_MAJOR_VERSION = int(SDK_VERSION.split(".")[0])
 
 
@@ -50,6 +50,24 @@ class ActionManifest(BaseModel):
     has_preview: bool = True
 
 
+class MCPResourceManifest(BaseModel):
+    """A URI-addressable MCP resource the connector exposes (resources primitive)."""
+
+    name: str
+    description: str
+    address: str  # uri (static) or uri template
+    is_template: bool = False
+    mime_type: str = "text/plain"
+
+
+class PromptManifest(BaseModel):
+    """A prompt template the connector offers (prompts primitive)."""
+
+    name: str
+    description: str
+    arguments: list[str] = Field(default_factory=list)
+
+
 class DeploymentCompat(BaseModel):
     """Deployment-mode honesty: a connector must declare its network needs so
     air-gapped deployments can refuse network-dependent connectors."""
@@ -72,6 +90,8 @@ class Manifest(BaseModel):
     )
     resources: list[ResourceManifest] = Field(default_factory=list)
     actions: list[ActionManifest] = Field(default_factory=list)
+    mcp_resources: list[MCPResourceManifest] = Field(default_factory=list)
+    prompts: list[PromptManifest] = Field(default_factory=list)
     deployment: DeploymentCompat
 
     def to_json(self, *, indent: int = 2) -> str:

{deepquery_sdk-1.0.0 → deepquery_sdk-1.1.1}/src/deepquery_sdk/mcp_emit/emitter.py

@@ -24,14 +24,33 @@ from __future__ import annotations
 
 from typing import Any
 
+import re
+
 from mcp import types
 from mcp.server.lowlevel import Server
+from mcp.server.lowlevel.helper_types import ReadResourceContents
+from pydantic import AnyUrl
 
 from ..action import ActionSpec
 from ..classification import DQ_CONNECTOR, DQ_KIND, DQ_MUTATES, CapabilityKind, meta_for
 from ..connector import Connector
 from ..resource import ResourceSpec
 
+_TEMPLATE_VAR = re.compile(r"\{([a-zA-Z_][a-zA-Z0-9_]*)\}")
+
+
+def _match_template(template: str, uri: str) -> dict[str, str] | None:
+    """Match a URI against a `{var}` template, returning captured params or None."""
+    parts: list[str] = []
+    last = 0
+    for m in _TEMPLATE_VAR.finditer(template):
+        parts.append(re.escape(template[last:m.start()]))
+        parts.append(f"(?P<{m.group(1)}>[^/]+)")
+        last = m.end()
+    parts.append(re.escape(template[last:]))
+    match = re.match("^" + "".join(parts) + "$", uri)
+    return match.groupdict() if match else None
+
 # Names of the two control tools that drive the gated action lifecycle.
 EXECUTE_TOOL = "dq.execute_action"
 REJECT_TOOL = "dq.reject_action"
@@ -148,6 +167,78 @@ def emit_server(connector: Connector) -> Server:
 
         raise ValueError(f"unknown tool: {name!r}")
 
+    # -- resources (the MCP `resources` primitive) ------------------------
+    # Registering these handlers makes the emitted server advertise the
+    # `resources` capability automatically during the initialize handshake.
+    if connector.mcp_resources:
+        static_by_uri = {s.uri: s for s in connector.mcp_resources if not s.is_template}
+        template_specs = [s for s in connector.mcp_resources if s.is_template]
+
+        @server.list_resources()
+        async def _list_resources() -> list[types.Resource]:
+            return [
+                types.Resource(uri=AnyUrl(s.uri), name=s.name, description=s.description, mimeType=s.mime_type)
+                for s in connector.mcp_resources
+                if not s.is_template
+            ]
+
+        @server.list_resource_templates()
+        async def _list_resource_templates() -> list[types.ResourceTemplate]:
+            return [
+                types.ResourceTemplate(
+                    uriTemplate=s.uri_template, name=s.name, description=s.description, mimeType=s.mime_type
+                )
+                for s in template_specs
+            ]
+
+        @server.read_resource()
+        async def _read_resource(uri: AnyUrl):
+            uri_str = str(uri)
+            spec = static_by_uri.get(uri_str)
+            params: dict[str, str] = {}
+            if spec is None:
+                for tspec in template_specs:
+                    matched = _match_template(tspec.uri_template, uri_str)
+                    if matched is not None:
+                        spec, params = tspec, matched
+                        break
+            if spec is None:
+                raise ValueError(f"unknown resource: {uri_str}")
+            content = connector.read_mcp_resource(spec, params)
+            return [ReadResourceContents(content=content, mime_type=spec.mime_type)]
+
+    # -- prompts (the MCP `prompts` primitive) ----------------------------
+    if connector.prompts:
+        prompts_by_name = {s.name: s for s in connector.prompts}
+
+        @server.list_prompts()
+        async def _list_prompts() -> list[types.Prompt]:
+            return [
+                types.Prompt(
+                    name=s.name,
+                    description=s.description,
+                    arguments=[
+                        types.PromptArgument(name=a.name, description=a.description, required=a.required)
+                        for a in s.arguments
+                    ],
+                )
+                for s in connector.prompts
+            ]
+
+        @server.get_prompt()
+        async def _get_prompt(name: str, arguments: dict[str, str] | None):
+            spec = prompts_by_name.get(name)
+            if spec is None:
+                raise ValueError(f"unknown prompt: {name!r}")
+            messages = connector.render_prompt(spec, arguments or {})
+            return types.GetPromptResult(
+                description=spec.description,
+                messages=[
+                    types.PromptMessage(role=m["role"], content=types.TextContent(type="text", text=m["text"]))
+                    for m in messages
+                ],
+            )
+
     return server
 
 

deepquery_sdk-1.1.1/src/deepquery_sdk/mcp_resource.py

@@ -0,0 +1,83 @@
+"""MCP resource objects — URI-addressable data a connector exposes.
+
+Distinct from `@resource` (which declares a *read* and is emitted as a read-only
+**tool** for parameterized search). An `@mcp_resource` is the actual MCP
+`resources` primitive: data addressed by a URI (or a URI *template* with
+parameters), read via `resources/read`. Deep Query cites resource content by its
+URI, so a resource's content stays as citeable as a document chunk.
+
+See the MCP spec's `resources` capability.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Callable, Optional
+
+# Marker the Connector base scans for at subclass-definition time.
+_MCP_RESOURCE_MARKER = "__dq_mcp_resource__"
+
+
+class MCPResourceSpec:
+    """Declarative metadata for one MCP resource (static or templated)."""
+
+    def __init__(
+        self,
+        *,
+        name: str,
+        description: str,
+        uri: Optional[str],
+        uri_template: Optional[str],
+        mime_type: str,
+        attr_name: str,
+    ) -> None:
+        self.name = name
+        self.description = description
+        self.uri = uri
+        self.uri_template = uri_template
+        self.mime_type = mime_type
+        self.attr_name = attr_name
+
+    @property
+    def is_template(self) -> bool:
+        return self.uri_template is not None
+
+    @property
+    def address(self) -> str:
+        return self.uri_template if self.is_template else (self.uri or "")
+
+    def __repr__(self) -> str:  # pragma: no cover - debug aid
+        return f"MCPResourceSpec(name={self.name!r}, address={self.address!r})"
+
+
+def mcp_resource(
+    *,
+    description: str,
+    uri: Optional[str] = None,
+    uri_template: Optional[str] = None,
+    name: Optional[str] = None,
+    mime_type: str = "text/plain",
+) -> Callable[[Callable], Callable]:
+    """Declare a URI-addressable MCP resource.
+
+    Provide exactly one of `uri` (static) or `uri_template` (parameterized, e.g.
+    ``"docs://article/{slug}"`` — the decorated method then takes a `slug` arg).
+    The method returns the resource's content as ``str`` (text) or ``bytes`` (blob).
+    """
+    if bool(uri) == bool(uri_template):
+        raise ValueError("mcp_resource requires exactly one of `uri` or `uri_template`")
+
+    def deco(fn: Callable) -> Callable:
+        setattr(
+            fn,
+            _MCP_RESOURCE_MARKER,
+            {
+                "name": name or fn.__name__,
+                "description": description,
+                "uri": uri,
+                "uri_template": uri_template,
+                "mime_type": mime_type,
+            },
+        )
+        return fn
+
+    return deco

deepquery_sdk-1.1.1/src/deepquery_sdk/prompt.py

@@ -0,0 +1,75 @@
+"""MCP prompts — user-controlled prompt templates/workflows a connector offers.
+
+An `@prompt` is the MCP `prompts` primitive: a named template (with optional
+arguments) the host can surface to a *user*, fetched via `prompts/get`. Prompt
+content is user-controlled and is treated as untrusted by the consuming side —
+the connector just provides the template text.
+
+See the MCP spec's `prompts` capability.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Callable, Optional
+
+_PROMPT_MARKER = "__dq_prompt__"
+
+
+class PromptArgumentSpec:
+    def __init__(self, *, name: str, description: str = "", required: bool = False) -> None:
+        self.name = name
+        self.description = description
+        self.required = required
+
+
+class PromptSpec:
+    """Declarative metadata for one prompt template."""
+
+    def __init__(
+        self,
+        *,
+        name: str,
+        description: str,
+        arguments: list[PromptArgumentSpec],
+        attr_name: str,
+    ) -> None:
+        self.name = name
+        self.description = description
+        self.arguments = arguments
+        self.attr_name = attr_name
+
+    def __repr__(self) -> str:  # pragma: no cover - debug aid
+        return f"PromptSpec(name={self.name!r}, args={[a.name for a in self.arguments]})"
+
+
+def _coerce_arguments(arguments: Optional[list[Any]]) -> list[dict[str, Any]]:
+    """Accept either argument names (str) or dicts {name, description, required}."""
+    out: list[dict[str, Any]] = []
+    for a in arguments or []:
+        if isinstance(a, str):
+            out.append({"name": a, "description": "", "required": False})
+        elif isinstance(a, dict):
+            out.append({"name": a["name"], "description": a.get("description", ""), "required": bool(a.get("required", False))})
+        else:
+            raise TypeError(f"prompt argument must be a str or dict, got {type(a).__name__}")
+    return out
+
+
+def prompt(
+    *,
+    description: str,
+    name: Optional[str] = None,
+    arguments: Optional[list[Any]] = None,
+) -> Callable[[Callable], Callable]:
+    """Declare a prompt template.
+
+    The decorated method receives the prompt's arguments and returns either a
+    ``str`` (a single user-role message) or a list of ``{"role", "text"}`` dicts.
+    """
+    coerced = _coerce_arguments(arguments)
+
+    def deco(fn: Callable) -> Callable:
+        setattr(fn, _PROMPT_MARKER, {"name": name or fn.__name__, "description": description, "arguments": coerced})
+        return fn
+
+    return deco

{deepquery_sdk-1.0.0 → deepquery_sdk-1.1.1}/src/deepquery_sdk/validation.py

@@ -106,7 +106,16 @@ class _MutationVisitor(ast.NodeVisitor):
 
 
 def _check_descriptions(connector: Connector, report: ValidationReport) -> None:
-    for spec in list(connector.resources) + list(connector.actions):
+    # Resources/actions/mcp-resources/prompts all expose natural-language
+    # descriptions read by the agent — each must be present and is an injection
+    # surface (§13).
+    everything = (
+        list(connector.resources)
+        + list(connector.actions)
+        + list(connector.mcp_resources)
+        + list(connector.prompts)
+    )
+    for spec in everything:
         if not (spec.description or "").strip():
             report.error("DESC_MISSING", f"capability '{spec.name}' has an empty description (§4).")
         elif _INJECTION_MARKERS.search(spec.description):

{deepquery_sdk-1.0.0 → deepquery_sdk-1.1.1}/tests/test_phase4.py

@@ -39,7 +39,7 @@ def _run(argv: list[str]) -> int:
 # Version single-source
 # --------------------------------------------------------------------------- #
 def test_version_is_single_sourced():
-    assert __version__ == SDK_VERSION == "1.0.0"
+    assert __version__ == SDK_VERSION == "1.1.1"
     assert SDK_MAJOR_VERSION == 1
     # The installed package version must match the in-code version.
     assert importlib.metadata.version("deepquery-sdk") == SDK_VERSION

deepquery_sdk-1.1.1/tests/test_resources_prompts.py

@@ -0,0 +1,104 @@
+"""Tests for SDK 1.1.0 — emitting the MCP `resources` and `prompts` primitives.
+
+A connector can declare URI-addressable resources (static + templated) with
+`@mcp_resource` and prompt templates with `@prompt`. The emitted server must
+advertise those capabilities and serve them over a real MCP client session.
+"""
+
+from __future__ import annotations
+
+import importlib.metadata
+
+import pytest
+
+from deepquery_sdk import (
+    Connector,
+    SDK_VERSION,
+    mcp_resource,
+    prompt,
+    resource,
+)
+from deepquery_sdk.mcp_emit import emit_server
+
+from mcp.shared.memory import create_connected_server_and_client_session
+from pydantic import AnyUrl
+
+
+class DocsConnector(Connector):
+    name = "docs"
+    version = "1.1.0"
+    description = "Exposes documents as MCP resources and a prompt template."
+
+    @resource(description="Search docs.", input_schema={"type": "object", "properties": {"q": {"type": "string"}}})
+    def search(self, q: str = ""):
+        return [self.cite({"q": q}, source_object_id="s1", title_or_label="search result")]
+
+    @mcp_resource(uri="docs://readme", name="README", description="The project readme.", mime_type="text/markdown")
+    def readme(self) -> str:
+        return "# Hello\nThis is the readme."
+
+    @mcp_resource(uri_template="docs://article/{slug}", name="Article", description="An article by slug.")
+    def article(self, slug: str) -> str:
+        return f"Article: {slug}"
+
+    @prompt(description="Summarize a ticket.",
+            arguments=[{"name": "ticket_id", "description": "The ticket id", "required": True}])
+    def summarize(self, ticket_id: str) -> str:
+        return f"Please summarize ticket {ticket_id}."
+
+
+def test_manifest_lists_resources_and_prompts():
+    m = DocsConnector().build_manifest()
+    assert {r.name for r in m.mcp_resources} == {"README", "Article"}
+    templated = {r.name: r.is_template for r in m.mcp_resources}
+    assert templated == {"README": False, "Article": True}
+    assert [p.name for p in m.prompts] == ["summarize"]
+    assert m.prompts[0].arguments == ["ticket_id"]
+    # The existing read (@resource) is still emitted as a tool, not an mcp_resource.
+    assert [r.name for r in m.resources] == ["search"]
+
+
+def test_version_is_single_sourced():
+    assert SDK_VERSION == "1.1.1"
+    assert importlib.metadata.version("deepquery-sdk") == SDK_VERSION
+
+
+async def test_emitted_server_serves_resources_and_prompts():
+    server = emit_server(DocsConnector())
+    async with create_connected_server_and_client_session(server) as client:
+        init = await client.initialize()
+        caps = init.capabilities
+        assert caps.tools is not None and caps.resources is not None and caps.prompts is not None
+
+        # resources/list + resources/read (static)
+        resources = (await client.list_resources()).resources
+        assert any(str(r.uri) == "docs://readme" for r in resources)
+        content = await client.read_resource(AnyUrl("docs://readme"))
+        assert "readme" in content.contents[0].text.lower()
+        assert content.contents[0].mimeType == "text/markdown"
+
+        # resource template
+        templates = (await client.list_resource_templates()).resourceTemplates
+        assert any(t.uriTemplate == "docs://article/{slug}" for t in templates)
+        article = await client.read_resource(AnyUrl("docs://article/mcp-101"))
+        assert article.contents[0].text == "Article: mcp-101"
+
+        # prompts/list + prompts/get
+        prompts = (await client.list_prompts()).prompts
+        assert prompts[0].name == "summarize"
+        assert prompts[0].arguments[0].name == "ticket_id"
+        got = await client.get_prompt("summarize", {"ticket_id": "OPS-9"})
+        assert "OPS-9" in got.messages[0].content.text
+
+
+def test_resource_only_connector_advertises_resources():
+    class ResOnly(Connector):
+        name = "ro"
+        version = "1.1.0"
+
+        @mcp_resource(uri="x://a", name="A", description="a")
+        def a(self) -> str:
+            return "a"
+
+    tools_present = bool(ResOnly().mcp_resources)
+    assert tools_present