multi-agent-platform 0.1.0__py3-none-any.whl

map_client/project_config.py

@@ -0,0 +1,153 @@
+"""Project-local MAP identity: `.map/` config + persona tokens."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from map_client.client import MAPClient
+
+MAP_DIR_NAME = ".map"
+CONFIG_FILE = "config.yaml"
+AGENTS_FILE = "agents.yaml"
+AGENTS_LOCAL_FILE = "agents.local.yaml"
+DEFAULT_PERSONA = "host"
+
+BOOTSTRAP_HINT = (
+    "Run:\n"
+    "  map bootstrap --key <project-key> --name \"<Project Name>\" --api-url http://localhost:8001\n"
+    f"Or copy from {MAP_DIR_NAME}/config.yaml.example."
+)
+
+
+def missing_map_config_message() -> str:
+    return f"No {MAP_DIR_NAME}/{CONFIG_FILE} found. {BOOTSTRAP_HINT}"
+
+
+@dataclass(frozen=True)
+class PersonaInfo:
+    name: str
+    agent_name: str
+    description: str | None = None
+    role: str | None = None
+
+
+@dataclass(frozen=True)
+class ProjectMapConfig:
+    map_dir: Path
+    api_url: str
+    project_key: str
+    project_id: str | None
+    default_persona: str
+    personas: dict[str, PersonaInfo]
+    tokens: dict[str, str]
+
+    def token_for(self, persona: str) -> str:
+        if persona not in self.tokens:
+            known = ", ".join(sorted(self.tokens)) or "(none)"
+            raise ValueError(f"Unknown or missing token for persona '{persona}'. Known: {known}")
+        return self.tokens[persona]
+
+    def client_for(self, persona: str | None = None, *, transport: Any = None) -> MAPClient:
+        effective = persona or self.default_persona
+        return MAPClient(self.api_url, self.token_for(effective), transport=transport)
+
+
+def find_map_dir(start: Path | None = None) -> Path | None:
+    current = (start or Path.cwd()).resolve()
+    for path in [current, *current.parents]:
+        map_dir = path / MAP_DIR_NAME
+        if (map_dir / CONFIG_FILE).is_file():
+            return map_dir
+    return None
+
+
+def _read_yaml(path: Path) -> dict[str, Any]:
+    if not path.is_file():
+        return {}
+    data = yaml.safe_load(path.read_text(encoding="utf-8"))
+    return data if isinstance(data, dict) else {}
+
+
+def load_project_map_config(
+    project_root: Path | None = None,
+    *,
+    map_dir: Path | None = None,
+) -> ProjectMapConfig:
+    resolved_map_dir = map_dir or find_map_dir(project_root)
+    if resolved_map_dir is None:
+        raise ValueError(missing_map_config_message())
+
+    config = _read_yaml(resolved_map_dir / CONFIG_FILE)
+    agents_meta = _read_yaml(resolved_map_dir / AGENTS_FILE)
+    agents_local = _read_yaml(resolved_map_dir / AGENTS_LOCAL_FILE)
+
+    api_url = str(
+        config.get("api_url")
+        or os.environ.get("MAP_API_URL")
+        or "http://localhost:8000"
+    ).rstrip("/")
+    project_key = config.get("project_key")
+    if not project_key:
+        raise ValueError(f"{resolved_map_dir / CONFIG_FILE} must set project_key")
+
+    default_persona = str(config.get("default_persona") or DEFAULT_PERSONA)
+    raw_personas = agents_meta.get("personas") or {}
+    personas: dict[str, PersonaInfo] = {}
+    for key, value in raw_personas.items():
+        if not isinstance(value, dict):
+            continue
+        agent_name = value.get("agent_name")
+        if not agent_name:
+            raise ValueError(f"personas.{key}.agent_name is required in agents.yaml")
+        personas[key] = PersonaInfo(
+            name=key,
+            agent_name=str(agent_name),
+            description=value.get("description"),
+            role=value.get("role"),
+        )
+
+    raw_tokens = agents_local.get("personas") or {}
+    tokens: dict[str, str] = {}
+    for key, value in raw_tokens.items():
+        if isinstance(value, dict) and value.get("token"):
+            tokens[key] = str(value["token"])
+        elif isinstance(value, str) and value:
+            tokens[key] = value
+
+    return ProjectMapConfig(
+        map_dir=resolved_map_dir,
+        api_url=api_url,
+        project_key=str(project_key),
+        project_id=str(config["project_id"]) if config.get("project_id") else None,
+        default_persona=default_persona,
+        personas=personas,
+        tokens=tokens,
+    )
+
+
+def resolve_client(
+    *,
+    persona: str | None = None,
+    project_root: Path | None = None,
+    transport: Any = None,
+) -> MAPClient:
+    """Prefer project `.map/` persona; fall back to MAP_TOKEN / ~/.map/config.yaml."""
+    map_dir = find_map_dir(project_root)
+    if persona is not None or map_dir is not None:
+        cfg = load_project_map_config(project_root=project_root, map_dir=map_dir)
+        return cfg.client_for(persona, transport=transport)
+
+    from map_client.config import load_config
+
+    env_cfg = load_config()
+    if not env_cfg.get("token"):
+        raise ValueError(
+            f"No MAP credentials: add .map/agents.local.yaml ({BOOTSTRAP_HINT.strip()}) "
+            "or set MAP_TOKEN / ~/.map/config.yaml"
+        )
+    return MAPClient(env_cfg["api_url"], env_cfg["token"], transport=transport)

map_client/result_template.py

@@ -0,0 +1,167 @@
+"""b72d0542 I1.a — Result submission 4-段 template parser.
+
+Extracts 4 required sections from a result submission markdown body so the
+service layer can soft-warn on missing or malformed sections. Soft
+validation only — host is expected to follow up; the validator never
+blocks ``experiment complete``.
+
+The 4 required sections (markdown ``##`` H2 headings; case-insensitive
+substring match against the section name):
+
+* ``## summary`` — one-line result summary
+* ``## 实施 log`` — running logs, must contain at least one markdown link
+* ``## 风险`` — risks section
+* ``## acceptance`` — acceptance criteria checklist
+
+Behavior contract (pinned by ``docs/MAP-RESULT-SUBMISSION-TEMPLATE.md``):
+
+* No content (empty/None) → empty result (nothing to validate).
+* All 4 sections present + each with valid markdown link (where required)
+  → empty warnings list.
+* Missing any of the 4 sections → ``MISSING_TEMPLATE_SECTION`` warning.
+* ``## 实施 log`` section present but no ``[text](url)`` markdown link
+  → ``NO_LINK_IN_LOG_SECTION`` warning.
+* ``## 实施 log`` section has a malformed link (e.g. ``[text`` without
+  closing ``]`` or ``(`` without ``)``) → ``MALFORMED_MARKDOWN_LINK``
+  warning with the offending link text.
+
+Parsing helpers live here; service-level validation (warn codes,
+dataclass wrapper, valid=True invariant) lives in
+``server/services/template_service.py``.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+# 4 required section names (substring, lowercase compare).
+REQUIRED_SECTION_NAMES: tuple[str, ...] = (
+    "summary",
+    "实施 log",
+    "风险",
+    "acceptance",
+)
+
+# Match a ``## <heading>`` line. Section names may include spaces / CJK.
+_SECTION_HEADING_RE = re.compile(r"^##\s+(?P<name>.+?)\s*$", re.MULTILINE)
+
+# Match ``[text](url)`` markdown link. Greedy on text/url up to 1/2 parens
+# balanced; this is best-effort (markdown spec is more permissive than
+# this regex). Captures: 1=text, 2=url.
+_MARKDOWN_LINK_RE = re.compile(r"\[([^\]]+)\]\(([^)]+)\)")
+
+# Match an unbalanced markdown-link-like fragment: ``[text`` without ``]``
+# or ``(url`` without ``)``. Used to surface malformed links as warnings.
+_UNBALANCED_OPEN_BRACKET_RE = re.compile(r"\[[^\]\n]*$", re.MULTILINE)
+_UNBALANCED_OPEN_PAREN_RE = re.compile(r"\([^)\n]*$", re.MULTILINE)
+
+
+@dataclass(frozen=True)
+class ResultTemplateSections:
+    """Parsed sections of a result submission markdown body.
+
+    Each ``<section>_present`` is True iff a heading matching the
+    canonical name appears anywhere in the body. ``log_links`` is the
+    list of (text, url) tuples extracted from inside the ``## 实施 log``
+    section body (empty if section missing).
+    """
+
+    summary_present: bool
+    log_present: bool
+    risk_present: bool
+    acceptance_present: bool
+    log_links: tuple[tuple[str, str], ...] = ()
+
+    @property
+    def present(self) -> dict[str, bool]:
+        return {
+            "summary": self.summary_present,
+            "实施 log": self.log_present,
+            "风险": self.risk_present,
+            "acceptance": self.acceptance_present,
+        }
+
+
+def _extract_section_names(content: str) -> list[str]:
+    """Return the section names (text after ``##``) in document order."""
+    return [m.group("name").strip() for m in _SECTION_HEADING_RE.finditer(content)]
+
+
+def _slice_section_body(content: str, section_name: str) -> str | None:
+    """Return the body of the named ``##`` section (text after the heading
+    line until the next ``##`` heading or end of document), or None if
+    the section is not found.
+    """
+    headings = list(_SECTION_HEADING_RE.finditer(content))
+    target_idx: int | None = None
+    target_match_pos: int = -1
+    for idx, m in enumerate(headings):
+        if m.group("name").strip().lower() == section_name.lower():
+            target_idx = idx
+            target_match_pos = m.end()
+            break
+    if target_idx is None:
+        return None
+    if target_idx + 1 < len(headings):
+        return content[target_match_pos : headings[target_idx + 1].start()]
+    return content[target_match_pos:]
+
+
+def parse_result_submission(content: str | None) -> ResultTemplateSections:
+    """Parse a result submission markdown body.
+
+    Returns a :class:`ResultTemplateSections` summarising which of the 4
+    required sections are present and the markdown links found inside
+    the ``## 实施 log`` section.
+
+    Section detection is case-insensitive substring match (canonical
+    names compared via ``str.lower()``). The 4 canonical names are:
+
+    * ``summary``
+    * ``实施 log``
+    * ``风险``
+    * ``acceptance``
+    """
+    if not content:
+        return ResultTemplateSections(False, False, False, False, ())
+
+    sections = _extract_section_names(content)
+    section_set_lower = {s.lower() for s in sections}
+
+    summary_present = "summary" in section_set_lower
+    log_present = "实施 log" in section_set_lower
+    risk_present = "风险" in section_set_lower
+    acceptance_present = "acceptance" in section_set_lower
+
+    log_links: tuple[tuple[str, str], ...] = ()
+    if log_present:
+        log_body = _slice_section_body(content, "实施 log") or ""
+        log_links = tuple(
+            (m.group(1).strip(), m.group(2).strip())
+            for m in _MARKDOWN_LINK_RE.finditer(log_body)
+        )
+
+    return ResultTemplateSections(
+        summary_present=summary_present,
+        log_present=log_present,
+        risk_present=risk_present,
+        acceptance_present=acceptance_present,
+        log_links=log_links,
+    )
+
+
+def extract_malformed_link_fragment(log_body: str) -> str | None:
+    """Return the offending unbalanced fragment in ``## 实施 log`` body, if any.
+
+    Surfaces a hint for ``MALFORMED_MARKDOWN_LINK`` warnings. Returns
+    None when no unbalanced ``[...`` or ``(...`` tail is found (i.e. all
+    link-like fragments are well-formed or absent).
+    """
+    open_bracket = _UNBALANCED_OPEN_BRACKET_RE.search(log_body)
+    open_paren = _UNBALANCED_OPEN_PAREN_RE.search(log_body)
+    if open_bracket:
+        return open_bracket.group(0).strip()
+    if open_paren:
+        return open_paren.group(0).strip()
+    return None

map_client/testing.py

@@ -0,0 +1,27 @@
+"""Test utilities for in-process SDK/CLI tests."""
+
+from __future__ import annotations
+
+import httpx
+from starlette.testclient import TestClient
+
+
+class MAPTestClientTransport(httpx.BaseTransport):
+    def __init__(self, test_client: TestClient) -> None:
+        self._client = test_client
+
+    def handle_request(self, request: httpx.Request) -> httpx.Response:
+        path = request.url.path
+        if request.url.query:
+            path = f"{path}?{request.url.query.decode()}"
+        response = self._client.request(
+            request.method,
+            path,
+            headers=dict(request.headers),
+            content=request.content,
+        )
+        return httpx.Response(
+            status_code=response.status_code,
+            headers=response.headers,
+            content=response.content,
+        )

map_mcp/__init__.py

@@ -0,0 +1,4 @@
+from map_mcp.config import MCPServerSettings
+from map_mcp.server import build_server
+
+__all__ = ["build_server", "MCPServerSettings"]

map_mcp/_utils.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+import json
+import uuid
+from typing import Any
+
+from pydantic import BaseModel
+
+
+def dump(value: Any) -> Any:
+    if isinstance(value, BaseModel):
+        return value.model_dump(mode="json")
+    if isinstance(value, list):
+        return [dump(item) for item in value]
+    if isinstance(value, dict):
+        return {key: dump(item) for key, item in value.items()}
+    return value
+
+
+def parse_uuid(value: str, field: str) -> uuid.UUID:
+    try:
+        return uuid.UUID(value)
+    except ValueError as exc:
+        raise ValueError(f"Invalid UUID for {field}: {value}") from exc
+
+
+def dumps_json(value: Any) -> str:
+    return json.dumps(dump(value), ensure_ascii=False, indent=2)

map_mcp/auth.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+from contextvars import ContextVar
+
+from starlette.middleware.base import BaseHTTPMiddleware
+from starlette.requests import Request
+from starlette.responses import Response
+
+_request_bearer: ContextVar[str | None] = ContextVar("map_mcp_request_bearer", default=None)
+
+
+def get_request_bearer() -> str | None:
+    return _request_bearer.get()
+
+
+def parse_bearer_token(authorization: str | None) -> str | None:
+    if not authorization:
+        return None
+    scheme, _, credentials = authorization.partition(" ")
+    if scheme.lower() != "bearer" or not credentials:
+        return None
+    return credentials.strip() or None
+
+
+class BearerTokenMiddleware(BaseHTTPMiddleware):
+    """Extract Authorization: Bearer from each HTTP request into a context variable."""
+
+    async def dispatch(self, request: Request, call_next) -> Response:
+        token = parse_bearer_token(request.headers.get("authorization"))
+        reset = _request_bearer.set(token)
+        try:
+            return await call_next(request)
+        finally:
+            _request_bearer.reset(reset)

map_mcp/config.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from typing import Literal
+
+TransportName = Literal["stdio", "streamable-http", "sse"]
+
+
+@dataclass(frozen=True)
+class MCPServerSettings:
+    transport: TransportName
+    host: str
+    port: int
+    path: str
+
+    @classmethod
+    def from_env(
+        cls,
+        *,
+        transport: str | None = None,
+        host: str | None = None,
+        port: int | None = None,
+        path: str | None = None,
+    ) -> MCPServerSettings:
+        resolved_transport = (transport or os.environ.get("MAP_MCP_TRANSPORT", "stdio")).strip()
+        if resolved_transport not in ("stdio", "streamable-http", "sse"):
+            raise ValueError("transport must be one of: stdio, streamable-http, sse")
+
+        default_host = "127.0.0.1" if resolved_transport == "stdio" else "0.0.0.0"
+        resolved_host = (host or os.environ.get("MAP_MCP_HOST", default_host)).strip()
+        resolved_port = port or int(os.environ.get("MAP_MCP_PORT", "8080"))
+        resolved_path = (path or os.environ.get("MAP_MCP_PATH", "/mcp")).strip() or "/mcp"
+        if not resolved_path.startswith("/"):
+            resolved_path = f"/{resolved_path}"
+
+        return cls(
+            transport=resolved_transport,  # type: ignore[arg-type]
+            host=resolved_host,
+            port=resolved_port,
+            path=resolved_path,
+        )
+
+    @property
+    def url(self) -> str:
+        return f"http://{self.public_host}:{self.port}{self.path}"
+
+    @property
+    def public_host(self) -> str:
+        return "127.0.0.1" if self.host in {"0.0.0.0", "::"} else self.host

map_mcp/context.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+import uuid
+from dataclasses import dataclass
+
+from map_client.client import MAPClient
+from map_types import AgentRole
+
+from map_mcp._utils import parse_uuid
+
+
+@dataclass(frozen=True)
+class AgentContext:
+    role: AgentRole
+    project_id: uuid.UUID | None
+    project_key: str | None
+
+    @property
+    def is_admin(self) -> bool:
+        return self.role == AgentRole.admin
+
+    @classmethod
+    def from_client(cls, client: MAPClient) -> AgentContext:
+        me = client.get_me()
+        return cls(role=me.role, project_id=me.project_id, project_key=me.project_key)
+
+    def resolve_project_id(self, project_id: str | None) -> uuid.UUID:
+        if project_id:
+            pid = parse_uuid(project_id, "project_id")
+            if not self.is_admin and self.project_id and pid != self.project_id:
+                raise ValueError("Access denied: project_id does not match bound project")
+            return pid
+        if self.project_id:
+            return self.project_id
+        raise ValueError("project_id is required for admin agents without a bound project")
+
+    def require_admin(self) -> None:
+        if not self.is_admin:
+            raise ValueError("Admin role required for this tool")

map_mcp/main.py

@@ -0,0 +1,75 @@
+from __future__ import annotations
+
+import typer
+
+from map_mcp.config import MCPServerSettings
+
+cli = typer.Typer(
+    add_completion=False,
+    no_args_is_help=False,
+    invoke_without_command=True,
+    help="Multi-Agent Platform MCP server (stdio or HTTP).",
+)
+
+
+def _ensure_mcp_installed() -> None:
+    try:
+        from mcp.server.fastmcp import FastMCP  # noqa: F401
+    except ImportError as exc:
+        typer.echo(
+            "MCP support requires the 'mcp' package. Install with: pip install -e \".[mcp]\"",
+            err=True,
+        )
+        raise typer.Exit(code=1) from exc
+
+
+def _run_server(settings: MCPServerSettings) -> None:
+    from map_client import MAPClient
+    from map_client.config import load_config
+
+    from map_mcp.server import build_server
+
+    cfg = load_config()
+    api_url = cfg["api_url"]
+    # HTTP: identity comes from Authorization Bearer per connection.
+    # stdio: use MAP_TOKEN from env/config as the default client.
+    token = cfg.get("token")
+    client = MAPClient(api_url, token) if token and settings.transport == "stdio" else None
+    mcp = build_server(client, api_url=api_url, host=settings.host, port=settings.port, path=settings.path)
+
+    if settings.transport == "stdio":
+        mcp.run(transport="stdio")
+        return
+
+    if settings.transport == "streamable-http":
+        typer.echo(f"MAP MCP listening at {settings.url}", err=True)
+        mcp.run(transport="streamable-http")
+        return
+
+    typer.echo(f"MAP MCP SSE listening at http://{settings.public_host}:{settings.port}/sse", err=True)
+    mcp.run(transport="sse")
+
+
+@cli.callback()
+def main(
+    ctx: typer.Context,
+    transport: str | None = typer.Option(
+        None,
+        "--transport",
+        "-t",
+        help="Transport: stdio (default), streamable-http, or sse",
+    ),
+    host: str | None = typer.Option(None, "--host", help="Bind host for HTTP transports"),
+    port: int | None = typer.Option(None, "--port", "-p", help="Bind port for HTTP transports"),
+    path: str | None = typer.Option(None, "--path", help="HTTP MCP endpoint path (default: /mcp)"),
+) -> None:
+    """Run the MAP MCP server."""
+    if ctx.invoked_subcommand is not None:
+        return
+
+    _ensure_mcp_installed()
+    _run_server(MCPServerSettings.from_env(transport=transport, host=host, port=port, path=path))
+
+
+if __name__ == "__main__":
+    cli()