claude-fde-showcase

![CI](https://github.com/BenjisCollector/claude-fde-showcase/actions/workflows/ci.yml)

A compact, runnable demonstration of the three engineering primitives a Forward Deployed Engineer (FDE) / Applied AI engineer assembles when shipping production systems with Claude:

An MCP server that gives a model typed, auditable access to tools.
A sub-agent orchestrator that routes work to specialised, swappable workers.
An agent skill that packages a capability as a self-describing unit.

Everything here is real, deterministic, and offline. There are no fabricated benchmarks, no client data, and no API keys required. The core logic uses the Python standard library only; the mcp SDK is needed solely to serve the tools, and is imported lazily so the entire test suite and CI run green without it.

---

Architecture

┌──────────────────────────────────────────────────────────────┐
│  MCP client (Claude Desktop, custom agent, ...)               │
└───────────────────────────┬──────────────────────────────────┘
                            │  stdio (MCP)
                            ▼
┌──────────────────────────────────────────────────────────────┐
│  MCP server  (src/claude_fde_showcase/mcp_server/server.py)   │
│  FastMCP — imported lazily — registers 4 tools:               │
│    • search_docs   • summarise   • calculate   • list_docs    │
└───────────────────────────┬──────────────────────────────────┘
                            │  calls pure, std-lib-only logic
                            ▼
┌──────────────────────────────────────────────────────────────┐
│  Tool logic  (src/claude_fde_showcase/tools/)                 │
│    search.py      TF-IDF cosine retrieval over docs/          │
│    summarise.py   extractive (Luhn-style) summarisation       │
│    calculator.py  AST-sandboxed safe arithmetic              │
└──────────────────────────────────────────────────────────────┘
        ▲                                   ▲
        │ same functions reused by          │ same summariser reused by
        │                                   │
┌───────┴───────────────────┐     ┌─────────┴────────────────────┐
│ Sub-agent orchestrator    │     │ Agent skill                  │
│ subagents/orchestrator.py │     │ agent_skills/doc_summariser/ │
│  routes search/summarise/ │     │  SKILL.md + helper.py        │
│  calculate to sub-agents  │     │                              │
└───────────────────────────┘     └──────────────────────────────┘

The key design decision is the seam between transport and logic. The pure tool logic in tools/ has no third-party dependency and is unit-tested directly. The MCP server, the orchestrator, and the agent skill are all thin layers over that same logic, so each can be evolved (e.g. swapping a deterministic worker for a Claude-backed one) without touching the others.

Components

| Component | Path | What it actually does | | --- | --- | --- | | MCP server | src/claude_fde_showcase/mcp_server/server.py | FastMCP server exposing search_docs, summarise, calculate, list_docs. mcp is imported lazily inside build_server(). | | search_docs | src/claude_fde_showcase/tools/search.py | Loads docs/*.md into an in-memory TF-IDF index and ranks documents by cosine similarity — computed from scratch with the standard library. | | summarise | src/claude_fde_showcase/tools/summarise.py | Extractive summarisation: scores sentences by normalised term frequency (a Luhn-method variant) and returns the most salient ones in original order. | | calculate | src/claude_fde_showcase/tools/calculator.py | AST-sandboxed arithmetic. Parses to an AST and walks an explicit node allowlist — never evals the string, so code injection is impossible. | | Sub-agents | subagents/orchestrator.py | Orchestrator with explicit routing, infer_kind() classification, per-task error isolation, and result aggregation. | | Agent skill | agent_skills/doc_summariser/ | SKILL.md capability description + helper.py exposing summarise_document / gist, sharing the same summariser as the MCP tool. | | Docs corpus | docs/ | Five markdown documents that search_docs indexes and summarise can condense. | | Tests | tests/ | 60+ pytest cases over every tool, the orchestrator, and the skill — all passing without mcp installed. | | CI | .github/workflows/ci.yml | py_compile + pytest across Python 3.10–3.13, with mcp deliberately absent. |

---

How this maps to a Forward Deployed Engineer role

An FDE embeds with a customer and turns frontier-model capability into a production system. This repo is a miniature of that workflow:

Integration without leaking data — the MCP server. An FDE connects a

customer's private systems (a search index, a database, an internal API) to Claude through typed, auditable tools rather than dumping data into prompts. Here, search_docs plays that role over a local corpus; in a real engagement you swap DocStore for the customer's vector store behind the same interface and nothing downstream changes.

Decomposition you can test and evolve — the orchestrator. Production

agentic systems are not one giant prompt. The orchestrator shows the pattern an FDE scales: deterministic stub workers prove the routing, error isolation, and aggregation first, then individual workers are replaced with Claude-backed implementations one at a time, each independently evaluable.

Hardened tools over hallucinated output — the calculator. A model should

offload exact computation to deterministic code. The AST sandbox is exactly the kind of small, secure tool an FDE writes so the system computes instead of guessing — and the security tests prove the injection path is closed.

Reusable domain knowledge — the agent skill. SKILL.md is how an FDE

encodes a customer's house style and domain knowledge into a portable, self-describing unit that survives across sessions and teammates.

Ship-with-confidence discipline — tests + CI. Pure logic is separated from

transport so it can be tested fast, offline, with no keys. CI proves the whole thing compiles and passes with no mcp package and no network — the same reproducibility bar an FDE has to clear before anything reaches a customer.

---

Quickstart

python -m venv .venv && source .venv/bin/activate

# Install the package + test tooling (NO mcp SDK needed for any of the below):
pip install -e ".[dev]"

# Run the full test suite (offline, deterministic):
pytest

# Run the sub-agent orchestrator demo (search + summarise + calculate):
python -m subagents.orchestrator

# Run the agent-skill helper:
python agent_skills/doc_summariser/helper.py

Trying the pure logic in a REPL

from claude_fde_showcase.tools import search_docs, summarise_extractive, calculate

search_docs("how does an MCP server expose tools", limit=2)
summarise_extractive(open("docs/forward_deployed_engineering.md").read(), max_sentences=3)
calculate("sqrt(144) + 2 ** 5")   # -> 44.0

Running the actual MCP server

The MCP transport is the only part that needs the SDK:

pip install -e ".[mcp]"
claude-fde-mcp            # serves search_docs / summarise / calculate / list_docs over stdio

Point any MCP client (e.g. Claude Desktop) at that command to call the tools.

---

Testing & CI

tests/ contains focused suites: test_search.py, test_summarise.py,

test_calculator.py (including security/injection cases), test_orchestrator.py, and test_smoke.py (cross-cutting / skill integration).

The suite asserts that the server module imports and its logic runs without

the mcp package — guaranteeing the transport/logic separation actually holds.

.github/workflows/ci.yml installs only pytest, confirms mcp is absent,

byte-compiles every source file, runs pytest, and smoke-runs the demos — across Python 3.10 through 3.13.

What this is (and is not)

It is a faithful, runnable illustration of the FDE building blocks with real algorithms (TF-IDF retrieval, extractive summarisation, an AST sandbox) and a real test/CI story. It is not a benchmark, and it makes no claims about model accuracy or production results — every number you see is computed by the deterministic code in this repo.

License

MIT — see LICENSE.

claude-fde-showcase