agentx-kit 0.3.0__tar.gz → 0.4.0__tar.gz

{agentx_kit-0.3.0 → agentx_kit-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentx-kit
-Version: 0.3.0
+Version: 0.4.0
 Summary: An open-source, provider-agnostic agentic framework + interactive project scaffolder for LangChain and CrewAI. Pick your LLM provider, agents, RAG, memory, MCP tools and skills — generate a ready-to-run uv project.
 Project-URL: Homepage, https://github.com/muhammadyahiya/agentx-kit
 Project-URL: Repository, https://github.com/muhammadyahiya/agentx-kit
@@ -59,6 +59,8 @@ Provides-Extra: azure
 Requires-Dist: langchain-openai>=0.2.0; extra == 'azure'
 Provides-Extra: bedrock
 Requires-Dist: langchain-aws>=0.2.0; extra == 'bedrock'
+Provides-Extra: connector
+Requires-Dist: mcp>=1.2.0; extra == 'connector'
 Provides-Extra: crewai
 Requires-Dist: crewai>=0.70.0; extra == 'crewai'
 Provides-Extra: dashboard
@@ -260,6 +262,35 @@ It gives you, live as you edit:
 Run it inside a generated AgentX project and it reads/writes that project's
 `prompts.json`; run it anywhere else for a free-form prompt scratchpad.
 
+## 🔌 Use as a connector (Claude / Copilot / Codex)
+AgentX-Kit ships an **MCP server**, so any MCP-capable assistant can scaffold a
+complete project from **a single prompt with your problem statement**.
+
+```bash
+pip install "agentx-kit[connector]"
+agentx mcp --print-config        # prints the client config below
+```
+
+Add it to your client (then restart it):
+```jsonc
+// Claude Desktop / Codex / Copilot — under "mcpServers"
+{ "mcpServers": { "agentx-kit": { "command": "agentx", "args": ["mcp"] } } }
+```
+```bash
+# Claude Code one-liner
+claude mcp add agentx-kit -- agentx mcp
+```
+
+Now just ask, in plain language:
+> *“Build a customer-support agent that answers from our product docs and serves a REST API.”*
+
+The assistant calls AgentX-Kit's tools and you get a complete, runnable project:
+- **`recommend_project(problem_statement)`** — suggests framework, provider, agent count, and features.
+- **`create_agent_project(problem_statement, …)`** — generates the project (infers RAG/serve/memory/etc. from the statement, or take explicit overrides / `enterprise=true`) and returns the file tree + key file contents + run steps.
+- **`list_providers`**, **`analyze_prompt`**, **`optimize_prompt`** — provider list + prompt insights.
+
+So from one sentence the assistant produces a pre-wired project (prompts already seeded from your use case), ready to `uv sync && uv run`.
+
 ## 🏢 Enterprise pack
 Generate a production-shaped project with one flag — informed by a survey of
 CrewAI/LangGraph/create-llama/AgentStack/agno/pydantic-ai (see [RESEARCH.md](RESEARCH.md)):
@@ -309,6 +340,7 @@ llm = build_resilient_chat("openai", "gpt-4o-mini", fallbacks=[("anthropic", "cl
 | `observability` | `opentelemetry-*`, `openinference-*` | tracing |
 | `server` | `fastapi`, `uvicorn` | serving |
 | `dashboard` | `streamlit`, `tiktoken`, `pandas` | prompt observability dashboard |
+| `connector` | `mcp` | MCP server for Claude/Copilot/Codex |
 | `all` | everything above | kitchen sink |
 
 See [DESIGN.md](DESIGN.md) for the architecture and [RESEARCH.md](RESEARCH.md) for the competitive analysis behind these features.

{agentx_kit-0.3.0 → agentx_kit-0.4.0}/README.md

@@ -158,6 +158,35 @@ It gives you, live as you edit:
 Run it inside a generated AgentX project and it reads/writes that project's
 `prompts.json`; run it anywhere else for a free-form prompt scratchpad.
 
+## 🔌 Use as a connector (Claude / Copilot / Codex)
+AgentX-Kit ships an **MCP server**, so any MCP-capable assistant can scaffold a
+complete project from **a single prompt with your problem statement**.
+
+```bash
+pip install "agentx-kit[connector]"
+agentx mcp --print-config        # prints the client config below
+```
+
+Add it to your client (then restart it):
+```jsonc
+// Claude Desktop / Codex / Copilot — under "mcpServers"
+{ "mcpServers": { "agentx-kit": { "command": "agentx", "args": ["mcp"] } } }
+```
+```bash
+# Claude Code one-liner
+claude mcp add agentx-kit -- agentx mcp
+```
+
+Now just ask, in plain language:
+> *“Build a customer-support agent that answers from our product docs and serves a REST API.”*
+
+The assistant calls AgentX-Kit's tools and you get a complete, runnable project:
+- **`recommend_project(problem_statement)`** — suggests framework, provider, agent count, and features.
+- **`create_agent_project(problem_statement, …)`** — generates the project (infers RAG/serve/memory/etc. from the statement, or take explicit overrides / `enterprise=true`) and returns the file tree + key file contents + run steps.
+- **`list_providers`**, **`analyze_prompt`**, **`optimize_prompt`** — provider list + prompt insights.
+
+So from one sentence the assistant produces a pre-wired project (prompts already seeded from your use case), ready to `uv sync && uv run`.
+
 ## 🏢 Enterprise pack
 Generate a production-shaped project with one flag — informed by a survey of
 CrewAI/LangGraph/create-llama/AgentStack/agno/pydantic-ai (see [RESEARCH.md](RESEARCH.md)):
@@ -207,6 +236,7 @@ llm = build_resilient_chat("openai", "gpt-4o-mini", fallbacks=[("anthropic", "cl
 | `observability` | `opentelemetry-*`, `openinference-*` | tracing |
 | `server` | `fastapi`, `uvicorn` | serving |
 | `dashboard` | `streamlit`, `tiktoken`, `pandas` | prompt observability dashboard |
+| `connector` | `mcp` | MCP server for Claude/Copilot/Codex |
 | `all` | everything above | kitchen sink |
 
 See [DESIGN.md](DESIGN.md) for the architecture and [RESEARCH.md](RESEARCH.md) for the competitive analysis behind these features.

{agentx_kit-0.3.0 → agentx_kit-0.4.0}/pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 # PyPI distribution name (import name + CLI stay `agentx`; `agentx` was taken).
 name = "agentx-kit"
-version = "0.3.0"
+version = "0.4.0"
 description = "An open-source, provider-agnostic agentic framework + interactive project scaffolder for LangChain and CrewAI. Pick your LLM provider, agents, RAG, memory, MCP tools and skills — generate a ready-to-run uv project."
 readme = "README.md"
 requires-python = ">=3.10,<3.14"
@@ -60,6 +60,7 @@ observability = [
 ]
 server = ["fastapi>=0.110.0", "uvicorn[standard]>=0.29.0", "sse-starlette>=2.0.0"]
 dashboard = ["streamlit>=1.40.0", "tiktoken>=0.7.0", "pandas>=2.0.0"]
+connector = ["mcp>=1.2.0"]
 
 # ---- Bundles ----
 all = [
@@ -73,6 +74,7 @@ all = [
     "openinference-instrumentation-langchain>=0.1.0",
     "fastapi>=0.110.0", "uvicorn[standard]>=0.29.0", "sse-starlette>=2.0.0",
     "streamlit>=1.40.0", "tiktoken>=0.7.0", "pandas>=2.0.0",
+    "mcp>=1.2.0",
 ]
 dev = ["pytest>=8.0.0", "pytest-cov>=5.0.0"]
 

{agentx_kit-0.3.0 → agentx_kit-0.4.0}/src/agentx/__init__.py

@@ -16,7 +16,7 @@ is enough to get started.
 """
 from __future__ import annotations
 
-__version__ = "0.3.0"
+__version__ = "0.4.0"
 
 from .providers import (  # noqa: E402
     ProviderSpec,

{agentx_kit-0.3.0 → agentx_kit-0.4.0}/src/agentx/cli.py

@@ -68,6 +68,36 @@ def dashboard(
         raise typer.Exit(1) from exc
 
 
+@app.command()
+def mcp(
+    print_config: bool = typer.Option(False, "--print-config", help="Print MCP client config for Claude/Codex/Copilot and exit."),
+) -> None:
+    """Run AgentX-Kit as an MCP server (connector for Claude / Copilot / Codex).
+
+    Once connected, a single prompt with a problem statement generates a complete
+    project. Add it to a client with the config from `agentx mcp --print-config`.
+    """
+    if print_config:
+        import json
+
+        from .connector import client_config
+
+        cfg = client_config()
+        console.print("[bold]MCP client config[/] (Claude Desktop / Claude Code / Codex / Copilot):\n")
+        console.print(json.dumps(cfg, indent=2))
+        console.print("\n[bold]Claude Code one-liner:[/]")
+        console.print("  claude mcp add agentx-kit -- agentx mcp")
+        console.print("\n[dim]Add the JSON under \"mcpServers\" in your client's MCP config "
+                      "(e.g. claude_desktop_config.json), then restart the client.[/]")
+        return
+    try:
+        from .connector import run
+    except RuntimeError as exc:
+        console.print(f"[red]{exc}[/]")
+        raise typer.Exit(1) from exc
+    run()  # stdio; no console output (the client drives it)
+
+
 def _result_panel(result, spec: ProjectSpec) -> None:
     lines = [f"[bold green]✓[/] Project '{spec.slug}' created at:", f"  {result.target_dir}", ""]
     lines += [f"  • {m}" for m in result.messages]

agentx_kit-0.4.0/src/agentx/connector/__init__.py

@@ -0,0 +1,18 @@
+"""MCP connector — expose AgentX-Kit to Claude / Copilot / Codex.
+
+`recommend_spec` and `build_project_from_statement` are pure (no MCP dep);
+`build_server`/`run` require ``agentx-kit[connector]``.
+"""
+from .build import build_project_from_statement
+from .recommend import recommend_spec
+
+__all__ = ["recommend_spec", "build_project_from_statement", "build_server", "run", "client_config"]
+
+
+def __getattr__(name: str):
+    # Lazy: only import the MCP SDK when the server is actually requested.
+    if name in ("build_server", "run", "client_config"):
+        from . import server
+
+        return getattr(server, name)
+    raise AttributeError(name)

agentx_kit-0.4.0/src/agentx/connector/build.py

@@ -0,0 +1,111 @@
+"""Turn a problem statement (+ optional overrides) into a generated project.
+
+Pure orchestration over the scaffolder — no MCP dependency — so it's testable
+and reusable. The MCP tools in ``server.py`` are thin wrappers around this.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+from ..scaffold import AgentSpec, ProjectSpec, generate_project
+from .recommend import recommend_spec
+
+_ALL_FEATURES = ["rag", "memory", "mcp", "skills", "observability", "guardrails", "serve", "docker", "ci", "evals"]
+_KEY_FILES_MAX = 6000
+
+
+def _apply_features(spec: ProjectSpec, features: list[str]) -> None:
+    fl = set(features or [])
+    spec.use_rag = "rag" in fl
+    spec.memory = "both" if "memory" in fl else "none"
+    spec.use_mcp = "mcp" in fl
+    spec.use_skills = "skills" in fl
+    spec.observability = "observability" in fl
+    spec.guardrails = "guardrails" in fl
+    spec.serve = "serve" in fl
+    spec.docker = "docker" in fl
+    spec.ci = "ci" in fl
+    spec.evals = "evals" in fl
+
+
+def build_project_from_statement(
+    problem_statement: str,
+    name: str = "",
+    framework: str = "",
+    provider: str = "",
+    model: str = "",
+    agents: int = 0,
+    features: list[str] | None = None,
+    enterprise: bool = False,
+    output_dir: str = "",
+    create_venv: bool = False,
+    overwrite: bool = True,
+) -> dict:
+    """Generate a complete project for a problem statement; return a summary."""
+    rec = recommend_spec(problem_statement)
+    name = name or rec["name"]
+    framework = framework or rec["framework"]
+    provider = provider or rec["provider"]
+    model = model or rec["model"]
+    n_agents = agents or rec["agents"]
+    feats = list(features) if features is not None else list(rec["features"])
+
+    # First agent carries the role/goal/prompt derived from the problem statement.
+    agent_specs = [AgentSpec(name="assistant" if n_agents == 1 else "agent_1",
+                             role=rec["role"], goal=rec["goal"], system_prompt=rec["system_prompt"])]
+    for i in range(1, n_agents):
+        agent_specs.append(AgentSpec(name=f"agent_{i + 1}", role=rec["role"]))
+
+    spec = ProjectSpec(
+        name=name, framework=framework, provider=provider, model=model,
+        agents=agent_specs, prompt_style="custom", create_venv=create_venv,
+    )
+    if enterprise:
+        spec.enable_enterprise()
+        feats = _ALL_FEATURES
+    else:
+        _apply_features(spec, feats)
+
+    target = Path(output_dir).expanduser() if output_dir else Path.cwd() / spec.slug
+    result = generate_project(spec, target, overwrite=overwrite)
+    root = result.target_dir
+
+    # Collect a compact view for the calling LLM.
+    tree = sorted(str(p.relative_to(root)) for p in root.glob("**/*") if p.is_file())
+    pkg = spec.package
+    key_paths = [
+        "pyproject.toml", "prompts.json", "agentx.json",
+        f"src/{pkg}/main.py", f"src/{pkg}/agents.py", f"src/{pkg}/prompts.py",
+    ]
+    if spec.serve:
+        key_paths.append(f"src/{pkg}/server.py")
+    key_files = {}
+    for rel in key_paths:
+        fp = root / rel
+        if fp.exists():
+            key_files[rel] = fp.read_text(encoding="utf-8")[:_KEY_FILES_MAX]
+
+    run_cmd = (
+        f"uv run uvicorn {pkg}.server:app --reload" if spec.serve else f"uv run {spec.slug}"
+    )
+    next_steps = [
+        f"cd {root.name}",
+        "cp .env.example .env   # add your provider API key(s)",
+        "uv venv && uv sync",
+        run_cmd,
+    ]
+
+    return {
+        "ok": True,
+        "target_dir": str(root),
+        "name": spec.slug,
+        "framework": framework,
+        "provider": provider,
+        "model": model or "(provider default)",
+        "agents": [a.name for a in agent_specs],
+        "features": feats,
+        "rationale": rec["rationale"],
+        "file_tree": tree,
+        "key_files": key_files,
+        "next_steps": next_steps,
+    }

agentx_kit-0.4.0/src/agentx/connector/recommend.py

@@ -0,0 +1,116 @@
+"""Map a natural-language problem statement to a recommended ProjectSpec.
+
+Pure and dependency-free so it's testable and usable without the MCP SDK. The
+connector uses this to turn a single user prompt into a complete project.
+"""
+from __future__ import annotations
+
+import re
+
+_STOP = {
+    "a", "an", "the", "for", "with", "that", "this", "and", "or", "to", "of", "in",
+    "on", "is", "are", "be", "build", "create", "make", "want", "need", "should",
+    "able", "can", "will", "agent", "agents", "ai", "app", "application", "using",
+    "use", "my", "our", "me", "you", "it", "system", "assistant", "bot", "help",
+}
+
+_ROLE_MAP = [
+    (("support", "ticket", "helpdesk", "customer"), "Customer Support Agent"),
+    (("research", "literature", "analyze papers", "summarize papers"), "Research Agent"),
+    (("code", "developer", "programming", "refactor", "review pull"), "Coding Assistant"),
+    (("data", "analytics", "sql", "report", "dashboard"), "Data Analyst"),
+    (("sales", "lead", "crm", "outreach"), "Sales Assistant"),
+    (("legal", "contract", "compliance", "policy"), "Compliance Assistant"),
+    (("medical", "clinical", "patient", "health"), "Clinical Assistant"),
+    (("devops", "infrastructure", "kubernetes", "deploy"), "DevOps Assistant"),
+]
+
+
+def _has(text: str, *kw: str) -> bool:
+    return any(k in text for k in kw)
+
+
+def _slug_from(text: str) -> str:
+    words = [w for w in re.findall(r"[a-z0-9]+", text.lower()) if w not in _STOP and len(w) > 2]
+    picked = words[:3] or ["agentx", "app"]
+    return "-".join(picked)
+
+
+def _role_for(text: str) -> str:
+    for keys, role in _ROLE_MAP:
+        if _has(text, *keys):
+            return role
+    return "Assistant"
+
+
+def recommend_spec(problem_statement: str) -> dict:
+    """Return a recommended spec dict + rationale for a problem statement."""
+    text = (problem_statement or "").lower().strip()
+
+    multi = _has(text, "multi-agent", "multi agent", "multiple agents", "team of",
+                 "crew", "collaborat", "debate", "researcher and", "reviewer", "planner")
+    framework = "crewai" if multi else "langgraph"
+
+    rag = _has(text, "document", "knowledge", "docs", "rag", "retriev", "pdf",
+               "manual", "faq", "knowledge base", " kb", "our data", "company data",
+               "search through", "cite", "sources")
+    memory = _has(text, "remember", "conversation history", "multi-turn", "multi turn",
+                  "across sessions", "previous", "chat history", "follow-up", "follow up")
+    mcp = _has(text, "mcp", "external tool", "integrate with", "third-party", "third party",
+               "plugin", "connect to", "external api")
+    skills = _has(text, "guideline", "standard", "compliance", "policy", "style guide",
+                  "best practice", "framework method")
+    serve = _has(text, "api", "endpoint", "serve", "rest", "http", "backend",
+                 "microservice", "webhook", "chat ui", "web app")
+    production = _has(text, "production", "enterprise", "scalable", "observability",
+                      "monitor", "trace", "secure", "reliable", "deploy", "high traffic")
+    coding = _has(text, "coding", "write code", "code generation", "programming task")
+
+    features: list[str] = []
+    if rag:
+        features.append("rag")
+    if memory:
+        features.append("memory")
+    if mcp:
+        features.append("mcp")
+    if skills:
+        features.append("skills")
+    if serve or production:
+        features.append("serve")
+    if production:
+        features += ["observability", "guardrails", "docker", "ci", "evals"]
+    # de-dupe, stable order
+    seen: list[str] = []
+    for f in features:
+        if f not in seen:
+            seen.append(f)
+
+    agents = 3 if framework == "crewai" else 1
+    role = _role_for(text)
+    goal = (problem_statement or "Help the user accomplish their task accurately.").strip()
+    system_prompt = (
+        f"You are a {role}. {goal} "
+        "Be accurate and concise, use your tools/knowledge before guessing, "
+        "cite sources when available, and ask for clarification when the request is ambiguous."
+    )
+
+    rationale = (
+        f"Chose **{framework}** ({'multi-agent collaboration detected' if multi else 'single-agent task'}); "
+        f"features: {', '.join(seen) or 'none'}. "
+        f"{'RAG (knowledge grounding). ' if rag else ''}"
+        f"{'Serving/API layer. ' if serve or production else ''}"
+        f"{'Full enterprise pack (tracing/guardrails/docker/CI/evals). ' if production else ''}"
+    ).strip()
+
+    return {
+        "name": _slug_from(text),
+        "framework": framework,
+        "provider": "openai",
+        "model": "",
+        "agents": agents,
+        "role": role,
+        "goal": goal[:300],
+        "system_prompt": system_prompt[:600],
+        "features": seen,
+        "rationale": rationale,
+    }

agentx_kit-0.4.0/src/agentx/connector/server.py

@@ -0,0 +1,108 @@
+"""MCP server exposing AgentX-Kit to Claude / Copilot / Codex as a connector.
+
+Run over stdio with ``agentx mcp``. Any MCP-capable client (Claude Desktop,
+Claude Code, GitHub Copilot, OpenAI Codex) can then, from a single prompt with a
+problem statement, generate a complete, ready-to-run agent project.
+
+Tools:
+  • recommend_project(problem_statement)         → suggested stack + features
+  • create_agent_project(problem_statement, …)   → generates the project, returns files
+  • list_providers()                             → supported LLM providers
+  • analyze_prompt(prompt) / optimize_prompt(…)  → prompt insights
+"""
+from __future__ import annotations
+
+from typing import Any
+
+from ..providers import all_specs
+from .build import build_project_from_statement
+from .recommend import recommend_spec
+
+
+def build_server():
+    """Construct the FastMCP server. Requires ``agentx-kit[connector]``."""
+    try:
+        from mcp.server.fastmcp import FastMCP
+    except ImportError as exc:  # pragma: no cover
+        raise RuntimeError(
+            "The MCP connector needs the MCP SDK. Install it with:\n"
+            "    pip install 'agentx-kit[connector]'"
+        ) from exc
+
+    mcp = FastMCP("agentx-kit")
+
+    @mcp.tool()
+    def list_providers() -> list[dict]:
+        """List the LLM providers AgentX-Kit can target and the env vars each needs."""
+        return [
+            {"id": s.id, "label": s.label, "default_model": s.default_model, "env_vars": list(s.env_vars)}
+            for s in all_specs()
+        ]
+
+    @mcp.tool()
+    def recommend_project(problem_statement: str) -> dict:
+        """Recommend a framework, provider, agent count and features for a use case.
+
+        Call this first to preview the stack; then call create_agent_project.
+        """
+        return recommend_spec(problem_statement)
+
+    @mcp.tool()
+    def create_agent_project(
+        problem_statement: str,
+        name: str = "",
+        framework: str = "",
+        provider: str = "",
+        model: str = "",
+        agents: int = 0,
+        features: list[str] | None = None,
+        enterprise: bool = False,
+        output_dir: str = "",
+    ) -> dict:
+        """Generate a complete, runnable agent project from a problem statement.
+
+        Leave optional args blank to let AgentX infer them from the problem
+        statement. ``features`` may include: rag, memory, mcp, skills,
+        observability, guardrails, serve, docker, ci, evals. Set ``enterprise``
+        true for the full production pack. Returns the target dir, file tree,
+        key file contents, and run steps.
+        """
+        try:
+            return build_project_from_statement(
+                problem_statement, name=name, framework=framework, provider=provider,
+                model=model, agents=agents, features=features, enterprise=enterprise,
+                output_dir=output_dir, create_venv=False, overwrite=True,
+            )
+        except Exception as exc:  # noqa: BLE001
+            return {"ok": False, "error": str(exc)}
+
+    @mcp.tool()
+    def analyze_prompt(prompt: str, model: str = "gpt-4o-mini") -> dict:
+        """Analyse a prompt: token count, quality score (0-100), suggestions, warnings."""
+        from ..insights import analyze_prompt as _analyze
+
+        a = _analyze(prompt, model)
+        return {
+            "tokens": a.tokens, "quality_score": a.quality_score,
+            "checks": a.checks, "suggestions": a.suggestions, "warnings": a.warnings,
+        }
+
+    @mcp.tool()
+    def optimize_prompt(prompt: str, provider: str = "openai", model: str = "", feedback: str = "") -> dict:
+        """Refine a prompt with an LLM (preserving intent); returns improved prompt + rationale."""
+        from ..insights import optimize_prompt as _optimize
+
+        r = _optimize(prompt, provider, model or None, feedback=feedback)
+        return {"ok": r.ok, "improved": r.improved, "rationale": r.rationale, "error": r.error}
+
+    return mcp
+
+
+def run() -> None:
+    """Run the MCP server over stdio (for Claude/Copilot/Codex)."""
+    build_server().run()
+
+
+def client_config(command: str = "agentx") -> dict[str, Any]:
+    """Return an MCP client config snippet for this server."""
+    return {"mcpServers": {"agentx-kit": {"command": command, "args": ["mcp"]}}}

agentx_kit-0.4.0/tests/test_connector.py

@@ -0,0 +1,70 @@
+"""Tests for the MCP connector's recommender + project builder (no MCP transport)."""
+import py_compile
+
+from agentx.connector import build_project_from_statement, recommend_spec
+
+
+# ----- recommender heuristics -----
+def test_recommend_rag_support_use_case():
+    rec = recommend_spec("Build a customer support agent that answers from our help docs and PDFs.")
+    assert rec["framework"] == "langgraph"
+    assert "rag" in rec["features"]
+    assert rec["role"] == "Customer Support Agent"
+    assert rec["name"]  # non-empty slug
+
+
+def test_recommend_multi_agent_research():
+    rec = recommend_spec("A team of agents: a researcher and a reviewer that collaborate to write reports.")
+    assert rec["framework"] == "crewai"
+    assert rec["agents"] >= 2
+
+
+def test_recommend_production_api_enables_enterprise_features():
+    rec = recommend_spec("Production-ready REST API agent, scalable with observability and monitoring.")
+    for f in ("serve", "observability", "guardrails", "docker", "ci", "evals"):
+        assert f in rec["features"], f
+
+
+def test_recommend_minimal():
+    rec = recommend_spec("just chat with me")
+    assert rec["framework"] == "langgraph"
+    assert rec["features"] == []
+
+
+# ----- builder produces a real, compilable project -----
+def test_build_project_from_statement(tmp_path):
+    out = build_project_from_statement(
+        "Build a support agent that answers from our documentation and serves an API.",
+        output_dir=str(tmp_path / "proj"), create_venv=False, overwrite=True,
+    )
+    assert out["ok"] is True
+    assert "rag" in out["features"] and "serve" in out["features"]
+    assert "prompts.json" in out["key_files"]
+    assert "agentx.json" in out["key_files"]
+    # the derived system prompt carries the use case
+    import json
+    prompts = json.loads(out["key_files"]["prompts.json"])
+    sp = next(iter(prompts["agents"].values()))["system_prompt"]
+    assert "documentation" in sp.lower() or "support" in sp.lower()
+    # generated python compiles
+    from pathlib import Path
+    for py in Path(out["target_dir"]).glob("**/*.py"):
+        py_compile.compile(str(py), doraise=True)
+    assert any(p.endswith("server.py") for p in out["file_tree"])
+
+
+def test_build_explicit_overrides(tmp_path):
+    out = build_project_from_statement(
+        "chat assistant", name="my-bot", framework="crewai", provider="ollama",
+        features=["memory"], output_dir=str(tmp_path / "o"), create_venv=False, overwrite=True,
+    )
+    assert out["name"] == "my-bot"
+    assert out["framework"] == "crewai"
+    assert "memory" in out["features"]
+
+
+def test_client_config_shape():
+    from agentx.connector import client_config
+
+    cfg = client_config()
+    assert cfg["mcpServers"]["agentx-kit"]["args"] == ["mcp"]