Restructure project for crypto intelligence patterns with test infrastructure

[ksopyla]

Summary

Major restructuring of the agent-patterns-lab project to align with the crypto intelligence platform vision:

• Restructured examples: Renamed and reorganized examples/01-orchestrator-pipeline/ with dedicated crypto intelligence agents (Research Planner, News Scanner, Intelligence Compiler) and added examples/02-mcp-tool-integration/ with MCP server configuration and 5 specialized agents (Community Analyst, Project Profiler, etc.)
• Test infrastructure: Added comprehensive test suites (unit, API, e2e) for both examples with pytest fixtures, async mocking patterns for LangChain/MCP tools, and test runner scripts
• Project foundation: Added project vision document, expanded curriculum with full 9-pattern progression, created .env.example, MCP server config, linting scripts, and CI workflow updates
• Cursor tooling: Added tester skill, testing-gate rule, project-vision rule, documentation-writer improvements, and local environment configuration updates

Commits included

1. test: add test infrastructure with unit, API, and e2e test suites
2. feat: add MCP server configuration and environment script
3. refactor: restructure example and curriculum for agent patterns
4. chore: update linting configuration and testing guidelines
5. refactor: update async mock implementations in unit tests
6. docs: update SKILL.md with mocking guidelines for LangChain/MCP tools
7. docs: enhance README and project vision documentation
8. docs: expand README with design patterns and project overview

Test plan

• Verify examples/01-orchestrator-pipeline/ tests pass with uv run pytest
• Verify examples/02-mcp-tool-integration/ tests pass with uv run pytest
• Confirm docker compose up --build works for both examples
• Check CI workflow runs successfully on the PR

---

Note

Medium Risk
Medium risk due to broad repo restructuring (example renames/new examples) plus CI/pre-commit, mypy, and test-runner changes that can break developer workflow or pipelines if misconfigured.

Overview
Refactors the repo from lesson-based examples to a crypto-intelligence pattern progression, including a new examples/01-orchestrator-pipeline (3-agent pipeline with DuckDuckGo search) and a new examples/02-mcp-tool-integration (5-agent pipeline plus a CoinGecko-backed crypto-data MCP server and MCP client lifecycle management).

Adds a standardized testing + quality gate: new per-example tests/unit, tests/api, and tests/e2e suites, a cross-repo scripts/testing/run_test_suite.py, and a per-directory scripts/linting/run_mypy.py to avoid monorepo duplicate-module issues; CI now runs pre-commit, uses the wrapper mypy script, and runs the full test suite with coverage.

Updates project foundations and tooling: expands top-level docs (README.md, docs/curriculum.md, new docs/vision.md), updates .env.example for MCP-related vars, bumps and simplifies .pre-commit-config.yaml (removes mypy hook), tweaks Makefile setup, and adds Cursor MCP/rules/skills plus .gitignore entries for Cursor state.

^{Written by Cursor Bugbot for commit dcb16bf. This will update automatically on new commits. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes and found 3 potential issues.

Bugbot Autofix prepared fixes for all 3 issues found in the latest run.

• ✅ Fixed: Wrong parameter name for DuckDuckGo search results
  • Changed num_results=8 to max_results=8 in both Pattern 01 and Pattern 02 news_scanner.py files to match the langchain-community>=0.3 API.
• ✅ Fixed: MCP client not entered as async context manager
  • Added explicit aenter() call in init_mcp() and aexit() call in close_mcp() to properly establish and close MCP server connections.
• ✅ Fixed: Test mock doesn't configure ainvoke method correctly
  • Changed mock configuration to explicitly set mock_search.ainvoke = AsyncMock(return_value=...) to ensure the ainvoke method returns the intended search results.

Or push these changes by commenting:

@cursor push b43e33b173

Preview (b43e33b173)

diff --git a/examples/01-orchestrator-pipeline/src/agents/news_scanner.py b/examples/01-orchestrator-pipeline/src/agents/news_scanner.py
--- a/examples/01-orchestrator-pipeline/src/agents/news_scanner.py
+++ b/examples/01-orchestrator-pipeline/src/agents/news_scanner.py
@@ -30,7 +30,7 @@
     verbose_log("NewsScanner", f"Searching for: {user_input[:80]}")
 
     search = DuckDuckGoSearchResults(
-        num_results=8,
+        max_results=8,
         output_format="list",
     )
     raw_results = await search.ainvoke(f"{user_input} crypto project news 2026")

diff --git a/examples/02-mcp-tool-integration/src/agents/news_scanner.py b/examples/02-mcp-tool-integration/src/agents/news_scanner.py
--- a/examples/02-mcp-tool-integration/src/agents/news_scanner.py
+++ b/examples/02-mcp-tool-integration/src/agents/news_scanner.py
@@ -31,7 +31,7 @@
     user_input = state["input"]
     verbose_log("NewsScanner", f"Searching for: {user_input[:80]}")
 
-    search = DuckDuckGoSearchResults(num_results=8, output_format="list")
+    search = DuckDuckGoSearchResults(max_results=8, output_format="list")
     raw_results = await search.ainvoke(f"{user_input} crypto project latest news 2026")
     verbose_log("NewsScanner", f"Got {len(raw_results) if isinstance(raw_results, list) else '?'} search results")
 

diff --git a/examples/02-mcp-tool-integration/src/mcp_setup.py b/examples/02-mcp-tool-integration/src/mcp_setup.py
--- a/examples/02-mcp-tool-integration/src/mcp_setup.py
+++ b/examples/02-mcp-tool-integration/src/mcp_setup.py
@@ -33,6 +33,7 @@
     verbose_log("MCP", f"Connecting to MCP servers: {list(config.keys())}")
 
     _mcp_client = MultiServerMCPClient(config)  # type: ignore[arg-type]
+    await _mcp_client.__aenter__()
     tools: list[BaseTool] = await _mcp_client.get_tools()  # type: ignore[misc]
     _mcp_tools = {t.name: t for t in tools}
     verbose_log("MCP", f"Loaded {len(_mcp_tools)} tools: {list(_mcp_tools.keys())}")
@@ -42,6 +43,7 @@
     """Disconnect from all MCP servers."""
     global _mcp_client, _mcp_tools  # noqa: PLW0603
     if _mcp_client:
+        await _mcp_client.__aexit__(None, None, None)
         _mcp_client = None
         _mcp_tools = {}
         verbose_log("MCP", "Disconnected from MCP servers")

diff --git a/examples/02-mcp-tool-integration/tests/unit/test_agent_nodes.py b/examples/02-mcp-tool-integration/tests/unit/test_agent_nodes.py
--- a/examples/02-mcp-tool-integration/tests/unit/test_agent_nodes.py
+++ b/examples/02-mcp-tool-integration/tests/unit/test_agent_nodes.py
@@ -46,7 +46,8 @@
     model = _DummyModel("Arbitrum announced Orbit chains. TVL exceeded $10B.")
     monkeypatch.setattr(news_scanner, "get_chat_model", lambda: model)
 
-    mock_search = AsyncMock(return_value=[{"title": "Arbitrum news", "snippet": "Orbit chains launched"}])
+    mock_search = AsyncMock()
+    mock_search.ainvoke = AsyncMock(return_value=[{"title": "Arbitrum news", "snippet": "Orbit chains launched"}])
     with patch.object(news_scanner, "DuckDuckGoSearchResults", return_value=mock_search):
         result = await news_scanner.news_scanner_node({"input": "Research Arbitrum", "plan": "1. News\n2. Tech"})

[cursor]

You have used all of your free Bugbot PR reviews.

To receive reviews on all of your PRs, visit the Cursor dashboard to activate Pro and start your 14-day free trial.

[ksopyla]

I have reviewd.