feat: add local tools and read-only remote MCP servers
Increment 6 of .scratch/solution-architect-agent/spec.md, test-first. - app/tools/mcp.py: MCP client and catalog exposing only allowlisted, readOnlyHint tools as framework-neutral ToolSpecs; unreachable servers and failed calls become discovery gaps; ADC auth with quota project. - app/tools/local.py: Mermaid structure check and Terraform fmt, validate and plan in a scratch copy; apply is never constructed. - Tool factory gives roles their named local tools and bundle MCP servers; pillar advisors get general-tier documentation tools. - providers/gcp.yaml: 42 allowlisted tools reviewed against live tools/list of 12 Google Cloud MCP servers (snapshot in providers/reviews/), excluding data-reading and secret-capable tools. - scripts/list-mcp-tools.py, docs/operations/mcp-access.md (IAM deny policy, service account roles), cloud-discovery and iac-validation Skills, MCP and Terraform settings, pytest asyncio auto mode. - 31 new tests; full suite 189 passed. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
@@ -1,7 +1,7 @@
|
||||
"""Load role files (agents/<role>.md) into RoleSpecs for one Cloud provider.
|
||||
|
||||
Role files are framework- and provider-neutral: frontmatter names the role, the
|
||||
Deliverable it owns, its local tool tiers, an optional budget and shared partials to
|
||||
Deliverable it owns, the local tools it uses, an optional budget and shared partials to
|
||||
include. The provider bundle supplies each role's Skills, MCP servers and model.
|
||||
"""
|
||||
|
||||
@@ -12,13 +12,13 @@ from pathlib import Path
|
||||
from app.agent_skills import SkillFormatError, split_frontmatter
|
||||
from app.agents.runtime import RoleSpec
|
||||
from app.execution.deliverables import DEPENDENCY_GRAPH, DeliverableKind
|
||||
from app.providers import TIERS, ProviderBundle
|
||||
from app.providers import ProviderBundle
|
||||
|
||||
ORCHESTRATOR = "orchestrator"
|
||||
PILLAR_ADVISOR = "pillar-advisor"
|
||||
PARTIALS_DIR = "partials"
|
||||
|
||||
_ALLOWED_FIELDS = {"role", "deliverable", "tool_tiers", "budget", "includes"}
|
||||
_ALLOWED_FIELDS = {"role", "deliverable", "tools", "budget", "includes"}
|
||||
|
||||
|
||||
class RoleConfigError(ValueError):
|
||||
@@ -96,10 +96,14 @@ def _load_role(
|
||||
elif deliverable is not None:
|
||||
raise fail(f"role {name!r} owns no Deliverable, but names {deliverable!r}")
|
||||
|
||||
tiers = tuple(frontmatter.get("tool_tiers") or ())
|
||||
bad_tiers = [tier for tier in tiers if tier not in TIERS]
|
||||
if bad_tiers:
|
||||
raise fail(f"'tool_tiers' {', '.join(bad_tiers)} must be among {TIERS}")
|
||||
tools = tuple(frontmatter.get("tools") or ())
|
||||
offered = {name for names in bundle.tools.values() for name in names}
|
||||
unknown_tools = [tool for tool in tools if tool not in offered]
|
||||
if unknown_tools:
|
||||
raise fail(
|
||||
f"'tools' {', '.join(unknown_tools)} are not offered by the "
|
||||
f"{bundle.name} provider bundle"
|
||||
)
|
||||
|
||||
budget = frontmatter.get("budget", default_budget)
|
||||
if not isinstance(budget, int) or budget < 1:
|
||||
@@ -119,7 +123,7 @@ def _load_role(
|
||||
instructions="\n\n".join(sections),
|
||||
budget=budget,
|
||||
skills=tuple(bundle.role_skills.get(name, ())),
|
||||
tool_tiers=tiers,
|
||||
tools=tools,
|
||||
mcp_servers=tuple(
|
||||
server.id
|
||||
for server in bundle.mcp_servers_for_role(name, include_preview_mcp)
|
||||
|
||||
@@ -19,7 +19,7 @@ class RoleSpec:
|
||||
instructions: str
|
||||
budget: int
|
||||
skills: tuple[str, ...] = ()
|
||||
tool_tiers: tuple[str, ...] = ()
|
||||
tools: tuple[str, ...] = () # local tool names, e.g. terraform_validate
|
||||
mcp_servers: tuple[str, ...] = ()
|
||||
model: str | None = None
|
||||
|
||||
|
||||
@@ -52,6 +52,13 @@ class Settings(BaseSettings):
|
||||
# Cloud Provider Bundle (providers/<name>.yaml) & Remote MCP Servers
|
||||
CLOUD_PROVIDER: str = "gcp"
|
||||
MCP_ENABLE_PREVIEW: bool = True
|
||||
MCP_QUOTA_PROJECT: str | None = None # defaults to the ADC project
|
||||
MCP_TIMEOUT_SECONDS: float = 30
|
||||
|
||||
# Local Terraform tools (fmt, validate, plan; never apply)
|
||||
TERRAFORM_BINARY: str = "terraform"
|
||||
TERRAFORM_TIMEOUT_SECONDS: float = 300
|
||||
TF_PLUGIN_CACHE_DIR: str | None = None
|
||||
|
||||
# Hierarchical Execution Engine (LangGraph state, ReAct agents)
|
||||
ORCHESTRATOR_BUDGET: int = 40
|
||||
|
||||
@@ -26,6 +26,7 @@ def pillar_consultation_tool(
|
||||
runtime: AgentRuntime,
|
||||
advisor: RoleSpec,
|
||||
pillar_skills: Mapping[str, str],
|
||||
extra_tools: Sequence[ToolSpec] = (),
|
||||
) -> ToolSpec:
|
||||
"""A tool that runs one pillar advisor per pillar, in parallel, each with its Skill."""
|
||||
|
||||
@@ -39,7 +40,9 @@ def pillar_consultation_tool(
|
||||
)
|
||||
results = await asyncio.gather(
|
||||
*(
|
||||
_advise(runtime, advisor, pillar, pillar_skills[pillar], brief)
|
||||
_advise(
|
||||
runtime, advisor, pillar, pillar_skills[pillar], brief, extra_tools
|
||||
)
|
||||
for pillar in chosen
|
||||
)
|
||||
)
|
||||
@@ -65,7 +68,12 @@ def pillar_consultation_tool(
|
||||
|
||||
|
||||
async def _advise(
|
||||
runtime: AgentRuntime, advisor: RoleSpec, pillar: str, skill: str, brief: str
|
||||
runtime: AgentRuntime,
|
||||
advisor: RoleSpec,
|
||||
pillar: str,
|
||||
skill: str,
|
||||
brief: str,
|
||||
extra_tools: Sequence[ToolSpec],
|
||||
) -> str:
|
||||
role = dataclasses.replace(advisor, skills=(skill,))
|
||||
task = AgentTask(
|
||||
@@ -74,7 +82,7 @@ async def _advise(
|
||||
context={"pillar": pillar, "brief": brief},
|
||||
)
|
||||
try:
|
||||
outcome = await runtime.run(role, task, [_submit_advice_tool()])
|
||||
outcome = await runtime.run(role, task, [_submit_advice_tool(), *extra_tools])
|
||||
except Exception as exc: # noqa: BLE001 - one failed advisor must not lose the others
|
||||
return f"## {pillar}\n\nNo guidance: the advisor failed ({exc})."
|
||||
if isinstance(outcome, Submitted):
|
||||
|
||||
@@ -1,6 +1,8 @@
|
||||
"""Which extra tools each role gets beyond the Execution tools.
|
||||
"""Which tools each role gets beyond the Execution tools.
|
||||
|
||||
Increment 6 adds the local general and cloud-read tools and remote MCP servers here.
|
||||
A role gets the local tools its role file names, the tools of the remote MCP servers
|
||||
the provider bundle assigns it, and, for the design advisor, the pillar consultation.
|
||||
Cloud-read gating is applied later, per Execution, by `specialist_tools`.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
@@ -12,22 +14,36 @@ from app.agents.runtime import AgentRuntime, RoleSpec, ToolSpec
|
||||
from app.execution.deliverables import DeliverableKind
|
||||
from app.execution.graph import ToolFactory
|
||||
from app.execution.pillars import pillar_consultation_tool
|
||||
from app.tools.mcp import McpCatalog
|
||||
|
||||
|
||||
def make_tool_factory(
|
||||
runtime: AgentRuntime,
|
||||
roles: Mapping[str, RoleSpec],
|
||||
pillar_skills: Mapping[str, str],
|
||||
*,
|
||||
local_tools: Sequence[ToolSpec] = (),
|
||||
catalog: McpCatalog | None = None,
|
||||
) -> ToolFactory:
|
||||
consult = (
|
||||
pillar_consultation_tool(runtime, roles[PILLAR_ADVISOR], pillar_skills)
|
||||
if pillar_skills and PILLAR_ADVISOR in roles
|
||||
else None
|
||||
)
|
||||
local_by_name = {tool.name: tool for tool in local_tools}
|
||||
|
||||
def mcp_tools(role: RoleSpec) -> list[ToolSpec]:
|
||||
return catalog.tools_for(role.mcp_servers) if catalog else []
|
||||
|
||||
consult = None
|
||||
advisor = roles.get(PILLAR_ADVISOR)
|
||||
if pillar_skills and advisor:
|
||||
# Pillar advisors can't ask for permission, so they get general-tier tools only.
|
||||
advisor_tools = [tool for tool in mcp_tools(advisor) if tool.tier == "general"]
|
||||
consult = pillar_consultation_tool(
|
||||
runtime, advisor, pillar_skills, extra_tools=advisor_tools
|
||||
)
|
||||
|
||||
def tools_for(role: RoleSpec, deliverable: str | None) -> Sequence[ToolSpec]:
|
||||
tools = [local_by_name[name] for name in role.tools if name in local_by_name]
|
||||
tools += mcp_tools(role)
|
||||
if consult and deliverable == DeliverableKind.DESIGN_RECOMMENDATIONS.value:
|
||||
return [consult]
|
||||
return []
|
||||
tools.append(consult)
|
||||
return tools
|
||||
|
||||
return tools_for
|
||||
|
||||
289
app/tools/local.py
Normal file
289
app/tools/local.py
Normal file
@@ -0,0 +1,289 @@
|
||||
"""Local tools: a Mermaid syntax check and Terraform checks in a scratch directory.
|
||||
|
||||
Terraform runs only fmt, init -backend=false, validate and plan. No command that
|
||||
changes cloud resources is ever constructed.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import asyncio
|
||||
import os
|
||||
import re
|
||||
import tempfile
|
||||
from collections.abc import Iterable, Mapping
|
||||
from dataclasses import dataclass
|
||||
from pathlib import Path, PurePosixPath
|
||||
from typing import Any
|
||||
|
||||
from app.agents.runtime import ToolResult, ToolSpec
|
||||
|
||||
_MAX_OUTPUT = 8_000
|
||||
_TERRAFORM_SUFFIXES = (".tf", ".tfvars", ".tf.json")
|
||||
_VARIABLE_NAME = re.compile(r"^[A-Za-z_][A-Za-z0-9_-]*$")
|
||||
_MERMAID_TYPES = (
|
||||
"flowchart",
|
||||
"graph",
|
||||
"sequenceDiagram",
|
||||
"classDiagram",
|
||||
"stateDiagram",
|
||||
"stateDiagram-v2",
|
||||
"erDiagram",
|
||||
"C4Context",
|
||||
"C4Container",
|
||||
"C4Component",
|
||||
"C4Deployment",
|
||||
"architecture-beta",
|
||||
"block-beta",
|
||||
)
|
||||
_BRACKETS = {"]": "[", ")": "(", "}": "{"}
|
||||
|
||||
|
||||
async def mermaid_check(diagram: str) -> ToolResult:
|
||||
"""A basic structural check; it does not render the diagram."""
|
||||
problems = []
|
||||
lines = [
|
||||
line.strip()
|
||||
for line in diagram.splitlines()
|
||||
if line.strip() and not line.strip().startswith("%%")
|
||||
]
|
||||
if not diagram.strip():
|
||||
problems.append("the diagram is empty")
|
||||
elif not lines or lines[0].split()[0] not in _MERMAID_TYPES:
|
||||
problems.append(
|
||||
"the first line must declare a diagram type, such as 'flowchart TD'"
|
||||
)
|
||||
for number, line in enumerate(diagram.splitlines(), start=1):
|
||||
stack: list[str] = []
|
||||
in_quotes = False
|
||||
for char in line:
|
||||
if char == '"':
|
||||
in_quotes = not in_quotes
|
||||
elif in_quotes:
|
||||
continue
|
||||
elif char in "[({":
|
||||
stack.append(char)
|
||||
elif char in _BRACKETS and (not stack or stack.pop() != _BRACKETS[char]):
|
||||
stack.append("!")
|
||||
break
|
||||
if stack:
|
||||
problems.append(f"Unbalanced brackets on line {number}: {line.strip()}")
|
||||
if problems:
|
||||
return ToolResult("Mermaid check failed: " + "; ".join(problems))
|
||||
return ToolResult("Mermaid check passed (structure only; not rendered).")
|
||||
|
||||
|
||||
@dataclass
|
||||
class TerraformRunner:
|
||||
binary: str = "terraform"
|
||||
timeout_seconds: float = 300
|
||||
plugin_cache_dir: str | None = None
|
||||
|
||||
async def fmt(self, files: Mapping[str, str]) -> ToolResult:
|
||||
refusal = _check_files(files)
|
||||
if refusal:
|
||||
return refusal
|
||||
with tempfile.TemporaryDirectory(prefix="tf-fmt-") as tmp:
|
||||
root = _write(Path(tmp), files)
|
||||
code, output = await self._run(
|
||||
[self.binary, "fmt", "-recursive", "-list=true"], root
|
||||
)
|
||||
if code != 0:
|
||||
return ToolResult(f"terraform fmt failed:\n{output}")
|
||||
changed = [
|
||||
name for name in files if (root / name).read_text() != files[name]
|
||||
]
|
||||
if not changed:
|
||||
return ToolResult("terraform fmt: all files are already formatted.")
|
||||
formatted = "\n\n".join(
|
||||
f"--- {name}\n{(root / name).read_text()}" for name in changed
|
||||
)
|
||||
return ToolResult(
|
||||
_clip(
|
||||
f"terraform fmt reformatted {len(changed)} file(s):\n\n{formatted}"
|
||||
)
|
||||
)
|
||||
|
||||
async def validate(self, files: Mapping[str, str]) -> ToolResult:
|
||||
refusal = _check_files(files)
|
||||
if refusal:
|
||||
return refusal
|
||||
with tempfile.TemporaryDirectory(prefix="tf-validate-") as tmp:
|
||||
root = _write(Path(tmp), files)
|
||||
failure = await self._init(root)
|
||||
if failure:
|
||||
return failure
|
||||
code, output = await self._run([self.binary, "validate", "-no-color"], root)
|
||||
verdict = "passed" if code == 0 else "failed"
|
||||
return ToolResult(_clip(f"terraform validate {verdict}:\n{output}"))
|
||||
|
||||
async def plan(
|
||||
self, files: Mapping[str, str], variables: Mapping[str, str] | None = None
|
||||
) -> ToolResult:
|
||||
refusal = _check_files(files)
|
||||
if refusal:
|
||||
return refusal
|
||||
variables = dict(variables or {})
|
||||
bad = [name for name in variables if not _VARIABLE_NAME.match(name)]
|
||||
if bad:
|
||||
return ToolResult(f"Refused: invalid variable names {', '.join(bad)}")
|
||||
with tempfile.TemporaryDirectory(prefix="tf-plan-") as tmp:
|
||||
root = _write(Path(tmp), files)
|
||||
failure = await self._init(root)
|
||||
if failure:
|
||||
return failure
|
||||
args = [
|
||||
self.binary,
|
||||
"plan",
|
||||
"-no-color",
|
||||
"-input=false",
|
||||
"-lock=false",
|
||||
"-refresh=true",
|
||||
*(f"-var={name}={value}" for name, value in variables.items()),
|
||||
]
|
||||
code, output = await self._run(args, root)
|
||||
verdict = "completed" if code == 0 else "failed"
|
||||
return ToolResult(
|
||||
_clip(f"terraform plan {verdict} (nothing was applied):\n{output}")
|
||||
)
|
||||
|
||||
async def _init(self, root: Path) -> ToolResult | None:
|
||||
code, output = await self._run(
|
||||
[self.binary, "init", "-backend=false", "-input=false", "-no-color"], root
|
||||
)
|
||||
if code != 0:
|
||||
return ToolResult(_clip(f"terraform init failed:\n{output}"))
|
||||
return None
|
||||
|
||||
async def _run(
|
||||
self, args: list[str], cwd: Path, env: Mapping[str, str] | None = None
|
||||
) -> tuple[int, str]:
|
||||
environment = {**os.environ, "TF_IN_AUTOMATION": "1", **(env or {})}
|
||||
if self.plugin_cache_dir:
|
||||
environment["TF_PLUGIN_CACHE_DIR"] = self.plugin_cache_dir
|
||||
try:
|
||||
process = await asyncio.create_subprocess_exec(
|
||||
*args,
|
||||
cwd=cwd,
|
||||
env=environment,
|
||||
stdout=asyncio.subprocess.PIPE,
|
||||
stderr=asyncio.subprocess.STDOUT,
|
||||
)
|
||||
except FileNotFoundError:
|
||||
return 127, f"{self.binary} is not installed or not on PATH."
|
||||
try:
|
||||
stdout, _ = await asyncio.wait_for(
|
||||
process.communicate(), timeout=self.timeout_seconds
|
||||
)
|
||||
except TimeoutError:
|
||||
process.kill()
|
||||
await process.wait()
|
||||
return 124, f"{' '.join(args[:2])} timed out after {self.timeout_seconds}s."
|
||||
return process.returncode or 0, stdout.decode(errors="replace")
|
||||
|
||||
|
||||
def _check_files(files: Mapping[str, str]) -> ToolResult | None:
|
||||
if not files:
|
||||
return ToolResult("Refused: provide at least one Terraform file.")
|
||||
bad = []
|
||||
for name in files:
|
||||
path = PurePosixPath(name)
|
||||
if (
|
||||
path.is_absolute()
|
||||
or ".." in path.parts
|
||||
or not name.endswith(_TERRAFORM_SUFFIXES)
|
||||
):
|
||||
bad.append(name)
|
||||
if bad:
|
||||
return ToolResult(
|
||||
"Refused: file names must be relative .tf, .tf.json or .tfvars paths "
|
||||
f"without '..': {', '.join(bad)}"
|
||||
)
|
||||
return None
|
||||
|
||||
|
||||
def _write(root: Path, files: Mapping[str, str]) -> Path:
|
||||
for name, content in files.items():
|
||||
target = root / name
|
||||
target.parent.mkdir(parents=True, exist_ok=True)
|
||||
target.write_text(content, encoding="utf-8")
|
||||
return root
|
||||
|
||||
|
||||
def _clip(text: str) -> str:
|
||||
return text if len(text) <= _MAX_OUTPUT else text[:_MAX_OUTPUT] + "\n[truncated]"
|
||||
|
||||
|
||||
_FILES_SCHEMA: dict[str, Any] = {
|
||||
"type": "object",
|
||||
"description": "Terraform files by relative path, e.g. {'main.tf': '...'}",
|
||||
"additionalProperties": {"type": "string"},
|
||||
}
|
||||
|
||||
LOCAL_TOOLS: dict[str, tuple[str, str]] = {
|
||||
"mermaid_check": ("general", "Check a Mermaid diagram's basic structure."),
|
||||
"terraform_fmt": ("general", "Format Terraform files and return any that changed."),
|
||||
"terraform_validate": (
|
||||
"general",
|
||||
"Validate Terraform files offline (init -backend=false, validate).",
|
||||
),
|
||||
"terraform_plan": (
|
||||
"cloud_read",
|
||||
"Preview Terraform against the live cloud environment with a plan. Never applies.",
|
||||
),
|
||||
}
|
||||
|
||||
|
||||
def local_tools(names: Iterable[str], runner: TerraformRunner) -> list[ToolSpec]:
|
||||
builders = {
|
||||
"mermaid_check": lambda: ToolSpec(
|
||||
"mermaid_check",
|
||||
LOCAL_TOOLS["mermaid_check"][1],
|
||||
{
|
||||
"type": "object",
|
||||
"properties": {"diagram": {"type": "string"}},
|
||||
"required": ["diagram"],
|
||||
},
|
||||
mermaid_check,
|
||||
tier="general",
|
||||
),
|
||||
"terraform_fmt": lambda: ToolSpec(
|
||||
"terraform_fmt",
|
||||
LOCAL_TOOLS["terraform_fmt"][1],
|
||||
{
|
||||
"type": "object",
|
||||
"properties": {"files": _FILES_SCHEMA},
|
||||
"required": ["files"],
|
||||
},
|
||||
runner.fmt,
|
||||
tier="general",
|
||||
),
|
||||
"terraform_validate": lambda: ToolSpec(
|
||||
"terraform_validate",
|
||||
LOCAL_TOOLS["terraform_validate"][1],
|
||||
{
|
||||
"type": "object",
|
||||
"properties": {"files": _FILES_SCHEMA},
|
||||
"required": ["files"],
|
||||
},
|
||||
runner.validate,
|
||||
tier="general",
|
||||
),
|
||||
"terraform_plan": lambda: ToolSpec(
|
||||
"terraform_plan",
|
||||
LOCAL_TOOLS["terraform_plan"][1],
|
||||
{
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"files": _FILES_SCHEMA,
|
||||
"variables": {
|
||||
"type": "object",
|
||||
"additionalProperties": {"type": "string"},
|
||||
},
|
||||
},
|
||||
"required": ["files"],
|
||||
},
|
||||
runner.plan,
|
||||
tier="cloud_read",
|
||||
),
|
||||
}
|
||||
return [builders[name]() for name in names]
|
||||
287
app/tools/mcp.py
Normal file
287
app/tools/mcp.py
Normal file
@@ -0,0 +1,287 @@
|
||||
"""Remote MCP servers hosted by the Cloud provider, exposed as read-only ToolSpecs.
|
||||
|
||||
Only tools on a server's reviewed allowlist are ever offered, and an allowlisted tool
|
||||
must declare `readOnlyHint: true` or loading fails. Tools keep the server's tier, so
|
||||
the Execution's cloud-read permission gate applies to them like any other tool.
|
||||
Failures become discovery gaps the agent records, never exceptions.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import asyncio
|
||||
import logging
|
||||
import re
|
||||
from collections.abc import AsyncIterator, Iterable, Mapping
|
||||
from contextlib import asynccontextmanager
|
||||
from dataclasses import dataclass
|
||||
from datetime import timedelta
|
||||
from typing import Any, Protocol
|
||||
|
||||
import httpx
|
||||
from mcp import ClientSession
|
||||
from mcp.client.streamable_http import streamable_http_client
|
||||
from mcp.shared._httpx_utils import create_mcp_http_client
|
||||
|
||||
from app.agents.runtime import ToolResult, ToolSpec
|
||||
from app.providers import McpServerSpec
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
GAP_INSTRUCTION = "Record this under 'Assumptions / discovery gaps' and continue."
|
||||
_MAX_TOOL_NAME = 64
|
||||
_CLOUD_PLATFORM_SCOPE = "https://www.googleapis.com/auth/cloud-platform"
|
||||
|
||||
|
||||
class McpConfigError(RuntimeError):
|
||||
"""An MCP server or its allowlist can't be used safely."""
|
||||
|
||||
|
||||
# --- auth ------------------------------------------------------------------------------
|
||||
|
||||
|
||||
class McpAuth(Protocol):
|
||||
async def headers(self) -> dict[str, str]: ...
|
||||
|
||||
|
||||
class NoAuth:
|
||||
async def headers(self) -> dict[str, str]:
|
||||
return {}
|
||||
|
||||
|
||||
class StaticHeadersAuth:
|
||||
def __init__(self, headers: Mapping[str, str]) -> None:
|
||||
self._headers = dict(headers)
|
||||
|
||||
async def headers(self) -> dict[str, str]:
|
||||
return dict(self._headers)
|
||||
|
||||
|
||||
class GoogleAdcAuth:
|
||||
"""Bearer token from Application Default Credentials, plus the quota project."""
|
||||
|
||||
def __init__(self, quota_project: str | None = None) -> None:
|
||||
self._quota_project = quota_project
|
||||
self._credentials: Any = None
|
||||
self._project: str | None = None
|
||||
self._lock = asyncio.Lock()
|
||||
|
||||
async def headers(self) -> dict[str, str]:
|
||||
async with self._lock:
|
||||
await asyncio.to_thread(self._refresh_if_needed)
|
||||
headers = {"Authorization": f"Bearer {self._credentials.token}"}
|
||||
project = self._quota_project or self._project
|
||||
if project:
|
||||
headers["X-Goog-User-Project"] = project
|
||||
return headers
|
||||
|
||||
def _refresh_if_needed(self) -> None:
|
||||
import google.auth
|
||||
import google.auth.transport.requests
|
||||
|
||||
if self._credentials is None:
|
||||
self._credentials, self._project = google.auth.default(
|
||||
scopes=[_CLOUD_PLATFORM_SCOPE]
|
||||
)
|
||||
if not self._credentials.valid:
|
||||
self._credentials.refresh(google.auth.transport.requests.Request())
|
||||
|
||||
|
||||
def auth_from_config(
|
||||
config: Mapping[str, Any], quota_project: str | None = None
|
||||
) -> McpAuth:
|
||||
kind = config.get("kind", "none")
|
||||
if kind == "none":
|
||||
return NoAuth()
|
||||
if kind == "google_adc":
|
||||
return GoogleAdcAuth(quota_project)
|
||||
raise McpConfigError(f"Unsupported mcp_auth kind {kind!r}; use google_adc or none")
|
||||
|
||||
|
||||
# --- client ----------------------------------------------------------------------------
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class McpToolInfo:
|
||||
name: str
|
||||
description: str
|
||||
input_schema: Mapping[str, Any]
|
||||
read_only: bool
|
||||
|
||||
|
||||
class McpClient:
|
||||
def __init__(
|
||||
self, server: McpServerSpec, auth: McpAuth, timeout: float = 30
|
||||
) -> None:
|
||||
self._server = server
|
||||
self._auth = auth
|
||||
self._timeout = timeout
|
||||
|
||||
@asynccontextmanager
|
||||
async def _session(self) -> AsyncIterator[ClientSession]:
|
||||
headers = await self._auth.headers()
|
||||
async with (
|
||||
create_mcp_http_client(
|
||||
headers=headers, timeout=httpx.Timeout(self._timeout)
|
||||
) as http_client,
|
||||
streamable_http_client(self._server.url, http_client=http_client) as (
|
||||
read,
|
||||
write,
|
||||
_,
|
||||
),
|
||||
ClientSession(
|
||||
read, write, read_timeout_seconds=timedelta(seconds=self._timeout)
|
||||
) as session,
|
||||
):
|
||||
await session.initialize()
|
||||
yield session
|
||||
|
||||
async def list_tools(self) -> list[McpToolInfo]:
|
||||
tools: list[McpToolInfo] = []
|
||||
async with self._session() as session:
|
||||
cursor = None
|
||||
while True:
|
||||
page = await session.list_tools(cursor=cursor)
|
||||
for tool in page.tools:
|
||||
annotations = tool.annotations
|
||||
tools.append(
|
||||
McpToolInfo(
|
||||
name=tool.name,
|
||||
description=tool.description or tool.title or tool.name,
|
||||
input_schema=tool.inputSchema or {"type": "object"},
|
||||
read_only=bool(annotations and annotations.readOnlyHint),
|
||||
)
|
||||
)
|
||||
cursor = page.nextCursor
|
||||
if not cursor:
|
||||
return tools
|
||||
|
||||
async def call_tool(
|
||||
self, name: str, arguments: Mapping[str, Any]
|
||||
) -> tuple[bool, str]:
|
||||
"""Return (is_error, text)."""
|
||||
async with self._session() as session:
|
||||
result = await session.call_tool(name, dict(arguments))
|
||||
text = "\n".join(
|
||||
getattr(item, "text", None) or str(item) for item in result.content
|
||||
)
|
||||
if not text and result.structuredContent is not None:
|
||||
text = str(result.structuredContent)
|
||||
return bool(result.isError), text
|
||||
|
||||
|
||||
# --- catalog ---------------------------------------------------------------------------
|
||||
|
||||
|
||||
def tool_name(server_id: str, tool: str) -> str:
|
||||
"""A tool name every model provider accepts: [A-Za-z0-9_-], at most 64 characters."""
|
||||
name = re.sub(r"[^A-Za-z0-9_-]", "_", f"{server_id}__{tool}")
|
||||
return name[:_MAX_TOOL_NAME]
|
||||
|
||||
|
||||
class McpCatalog:
|
||||
def __init__(self) -> None:
|
||||
self._tools: dict[str, list[ToolSpec]] = {}
|
||||
self.gaps: dict[str, str] = {}
|
||||
|
||||
@classmethod
|
||||
async def load(
|
||||
cls,
|
||||
servers: Iterable[McpServerSpec],
|
||||
auth: McpAuth,
|
||||
*,
|
||||
timeout: float = 30,
|
||||
max_result_chars: int = 20_000,
|
||||
) -> McpCatalog:
|
||||
catalog = cls()
|
||||
pending = [server for server in servers if server.allow]
|
||||
results = await asyncio.gather(
|
||||
*(McpClient(server, auth, timeout).list_tools() for server in pending),
|
||||
return_exceptions=True,
|
||||
)
|
||||
for server, listed in zip(pending, results, strict=True):
|
||||
client = McpClient(server, auth, timeout)
|
||||
if isinstance(listed, BaseException):
|
||||
reason = _describe(listed)
|
||||
logger.warning("MCP server %s unavailable: %s", server.id, reason)
|
||||
catalog.gaps[server.id] = reason
|
||||
catalog._tools[server.id] = [_unavailable_tool(server, reason)]
|
||||
continue
|
||||
|
||||
by_name = {tool.name: tool for tool in listed}
|
||||
not_read_only = [
|
||||
name
|
||||
for name in server.allow
|
||||
if name in by_name and not by_name[name].read_only
|
||||
]
|
||||
if not_read_only:
|
||||
raise McpConfigError(
|
||||
f"MCP server {server.id} allowlists tools not marked readOnlyHint: "
|
||||
f"{', '.join(not_read_only)}. Remove them from the allowlist."
|
||||
)
|
||||
missing = [name for name in server.allow if name not in by_name]
|
||||
if missing:
|
||||
catalog.gaps[server.id] = (
|
||||
f"allowlisted tools not offered by the server: {', '.join(missing)}"
|
||||
)
|
||||
catalog._tools[server.id] = [
|
||||
_tool_spec(server, client, by_name[name], max_result_chars)
|
||||
for name in server.allow
|
||||
if name in by_name
|
||||
]
|
||||
return catalog
|
||||
|
||||
def tools_for(self, server_ids: Iterable[str]) -> list[ToolSpec]:
|
||||
return [
|
||||
tool for server_id in server_ids for tool in self._tools.get(server_id, [])
|
||||
]
|
||||
|
||||
|
||||
def _tool_spec(
|
||||
server: McpServerSpec, client: McpClient, info: McpToolInfo, max_chars: int
|
||||
) -> ToolSpec:
|
||||
name = tool_name(server.id, info.name)
|
||||
|
||||
async def call(**arguments: Any) -> ToolResult:
|
||||
try:
|
||||
is_error, text = await client.call_tool(info.name, arguments)
|
||||
except Exception as exc: # noqa: BLE001 - a remote failure is a discovery gap
|
||||
return ToolResult(
|
||||
f"Discovery gap: {name} failed ({_describe(exc)}). {GAP_INSTRUCTION}"
|
||||
)
|
||||
if is_error:
|
||||
return ToolResult(
|
||||
f"Discovery gap: {name} failed ({text}). {GAP_INSTRUCTION}"
|
||||
)
|
||||
if len(text) > max_chars:
|
||||
text = text[:max_chars] + "\n[truncated]"
|
||||
return ToolResult(text)
|
||||
|
||||
return ToolSpec(
|
||||
name,
|
||||
f"[{server.id} MCP, read-only] {info.description}",
|
||||
dict(info.input_schema),
|
||||
call,
|
||||
tier=server.tier,
|
||||
)
|
||||
|
||||
|
||||
def _unavailable_tool(server: McpServerSpec, reason: str) -> ToolSpec:
|
||||
async def report(**_: Any) -> ToolResult:
|
||||
return ToolResult(
|
||||
f"Discovery gap: {server.id} MCP server unavailable ({reason}). {GAP_INSTRUCTION}"
|
||||
)
|
||||
|
||||
return ToolSpec(
|
||||
tool_name(server.id, "unavailable"),
|
||||
f"The {server.id} MCP server could not be reached; call to get the reason.",
|
||||
{"type": "object", "properties": {}},
|
||||
report,
|
||||
tier=server.tier,
|
||||
)
|
||||
|
||||
|
||||
def _describe(exc: BaseException) -> str:
|
||||
grouped = getattr(exc, "exceptions", None) # ExceptionGroup from anyio task groups
|
||||
if grouped:
|
||||
return _describe(grouped[0])
|
||||
return f"{type(exc).__name__}: {exc}" if str(exc) else type(exc).__name__
|
||||
Reference in New Issue
Block a user