convez.ai
MCP ServerIntegração & APIsIntermediário
GilbertAshivaka

DeepQuerySDK

GilbertAshivaka/DeepQuerySDK

Kit para desenvolver conectores MCP que integram sistemas externos ao DeepQuery

Ver no GitHub
InicialPluginScore · de 0 a 100

SDK Python para construir conectores customizados que emitem servidores MCP padrão, permitindo que DeepQuery consuma-os uniformemente. Inclui suporte a recursos, ações gated e autenticação OAuth 2.1 PKCE, com CLI e harness para testes.

Instalação

$npx convez-ai GilbertAshivaka/DeepQuerySDK

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
1

Casos de uso

  • Construir conectores para Jira, Slack, APIs corporativas
  • Integrar sistemas legados com agentes DeepQuery de forma segura
  • Implementar fluxos de aprovação (preview → execute) em ações mutantes

Veredito

SDK maduro (v1.1.0) com contrato estável para quem precisa estender DeepQuery via conectores. Excelente para integrar sistemas corporativos com aprovação humana obrigatória; requer experiência em Python e APIs REST.

README

A tradução para o português deste README ainda está na fila.

DeepQuerySDK — Connector Development Kit

Build connectors for Deep Query. A connector you write with this SDK emits a standard Model Context Protocol (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.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 and 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 checks (Phase 3), and the semver compatibility contract + packaging (Phase 4). The SDK contract is at major version 1: connectors declaring sdk_major_version = 1 are loadable by this runtime.

What you define

A connector is a subclass of Connector that declares three things:

You defineWhat it isGated?
Resourcesread-only data the agent can retrieve and citeno
Actionsoperations that change external stateyes (preview → execute)
Authhow the connector authenticates to the external systemn/a

Every read carries a provenance envelope so live data can be cited honestly. Every action is tagged dq.mutates: true in the emitted MCP server so Deep Query's approval gate knows it must be confirmed by a human.

Install (development)

# from the DeepQuerySDK/ folder, using the bundled venv
venv\Scripts\python.exe -m pip install -e .

60-second example

from deepquery_sdk import Connector, OAuth2Auth, resource, action

class JiraConnector(Connector):
    name = "jira"
    version = "0.1.0"
    description = "Read and act on Jira issues."

    # Declare OAuth 2.1 with least-privilege scopes. The gateway runs/stores the
    # grant and injects the token; this connector never stores credentials.
    auth = OAuth2Auth(
        authorize_endpoint="https://auth.atlassian.com/authorize",
        token_endpoint="https://auth.atlassian.com/oauth/token",
        scopes=["read:jira-work", "write:jira-work"],
    )
    requires_network = True

    @resource(description="Search Jira issues by text query.",
              input_schema={"type": "object",
                            "properties": {"query": {"type": "string"}},
                            "required": ["query"]})
    def search_issues(self, query: str):
        # ... call the real Jira API here ...
        return [
            self.cite(
                {"key": "DQ-431", "summary": "Login flow broken", "status": "In Review"},
                source_object_id="DQ-431",
                title_or_label="DQ-431 — Login flow broken",
                deep_link="https://example.atlassian.net/browse/DQ-431",
                mutability_note="live status field",
            )
        ]

    @action(description="Create a new Jira issue.",
            input_schema={"type": "object",
                          "properties": {"project": {"type": "string"},
                                         "summary": {"type": "string"}},
                          "required": ["project", "summary"]})
    def create_issue(self, project: str, summary: str):
        # only ever called after the approval gate confirms the preview.
        auth = self.apply_auth()  # headers built from the injected credential
        return {"created": f"{project}-NEW", "summary": summary}

    @create_issue.preview
    def _(self, project: str, summary: str) -> str:
        return f"Will create a new issue in project '{project}' titled '{summary}'."

Emit and serve it as an MCP server (the gateway injects the credential):

from deepquery_sdk import Credential, static_credential_provider
from deepquery_sdk.mcp_emit import run_stdio

connector = JiraConnector()
connector.set_credential_provider(static_credential_provider(Credential(token="...")))
run_stdio(connector)

The gated action lifecycle

Calling an action does not execute it. It returns a preview and a single-use approval token; the gateway drives the decision through two control tools:

call create_issue(args)        -> { status: "preview", approval_token, preview, arguments }
call dq.execute_action(token)  -> runs execute() for exactly those args  (after human approval)
call dq.reject_action(token)   -> discards the action; it never runs

The token binds the previewed arguments, so execute can never drift from what the human approved, and a rejected/used token can never run.

The deepquery CLI

deepquery scaffold acme-crm           # generate a new connector from the template
deepquery validate connector.py       # enforce the §5/§6/§13 safety contracts
deepquery manifest connector.py       # print/export the connector manifest
deepquery run-dev connector.py        # drive it interactively with the mock agent
deepquery emit connector.py --out dist/   # produce the deployable MCP server artifact

A target can be a path/to/connector.py, a directory containing connector.py, or a module.path:ClassName. validate is the gatekeeper: it statically scans @resource bodies for mutating calls and fails a resource that writes (a misclassified action), plus checks descriptions, manifest, deployment honesty, and least-privilege scopes.

The dev harness (deepquery_sdk.harness.MockAgent) discovers a connector over a real in-memory MCP session and drives reads (inspecting provenance) and the full preview → approve / reject action flow — the same sequence the real Agent Layer uses.

Try it without the test suite

# read path + classification + provenance, over a real stdio MCP server
venv\Scripts\python.exe examples\manual_client.py

# the full preview -> approve -> execute and preview -> reject flow
venv\Scripts\python.exe examples\manual_action_flow.py

See examples/jira_connector/ for the full runnable connector used in the Phase 1 and Phase 2 tests.

Versioning & compatibility

The SDK follows SemVer; see CHANGELOG.md. Every connector manifest declares the SDK major version it targets, and the gateway calls assert_compatible(manifest) before loading — refusing a connector built against an incompatible major with a clear error. Breaking changes ship with a guide in MIGRATIONS.md.

Release / publishing (maintainers)

Distributions are built with python -m build into dist/. To publish to PyPI:

python -m build                       # build sdist + wheel into dist/
python -m twine check dist/*          # validate metadata
python -m twine upload dist/*         # publish (requires PyPI credentials)

Tag the release v<version> and ensure version in pyproject.toml matches SDK_VERSION (a test enforces this against the installed package).

Ver o original no GitHub

Bom para

Relacionados