thinkcubator

Architecture

Zero-token execution boundary for local AI tool demos

A reusable local architecture that lets an LLM interpret natural language while deterministic Python and optional MCP boundaries own execution.

Built as a reusable building blockOct 6, 2026

AI-generated, human-reviewed: the first draft was generated by an AI agent; I fact-checked, tested, and edited it. AI use policy

Architecture#

Component flow from user request through local Ollama, host validation, direct or MCP invocation, and deterministic tools
Architecture: local intent extraction, host validation, direct execution, MCP execution, and deterministic tools

Dataflow#

  1. A caller provides either structured fields or a natural-language request.
  2. Structured fields go directly to the host validation contract.
  3. Natural language goes to local Ollama, which returns one proposed JSON intent object.
  4. The host validates exact fields, confidence range, intent allowlist, and parameter types.
  5. For direct execution, the host maps the validated intent to a fixed Python function.
  6. For MCP execution, the host maps the validated intent to a fixed MCP tool name.
  7. The deterministic Python implementation performs the work and returns structured output.

Components#

Component Role in this architecture
Local Ollama Translates natural language into proposed intent and parameters
Request contract Rejects malformed or invented model output before execution
Host router Owns the intent-to-function and intent-to-MCP-tool allowlists
MCP server adapter Exposes approved deterministic functions for discovery and invocation
Deterministic tools Perform calculator, email syntax, and mock support-ticket work
Unit tests or checks Prove invalid model output and unknown tools are rejected

Considerations#

Reliability#

Keep the deterministic function callable without Ollama or MCP. That gives you a fallback path and keeps core behavior testable without a model server.

Security#

Never accept a model-provided tool name, import path, shell command, or URL as executable authority. The model proposes domain intent; the host maps that intent to approved code.

Cost optimization#

The local version has no cloud or hosted-model cost. A hosted model changes the cost model from zero to token-based usage, and infrastructure changes it again.

Operational excellence#

Log the chosen intent, validation result, approved tool name, and deterministic output shape. Do not log raw user requests when they may contain sensitive content.

Performance efficiency#

Direct deterministic execution is the low-overhead path. MCP adds a boundary for reuse and discovery, not because the calculation needed an entourage.

When to use this architecture#

  • You want to teach or prototype tool boundaries without publishing a full repository.
  • You need a local demo where one request can run through direct and MCP paths.
  • You want model interpretation without model-owned execution.

When not to use it#

  • The caller already has perfect structured input and no other host needs discovery.
  • You need durable ticket storage, production identity, or network transport. Those are separate design decisions, not properties of this local pattern.

Build it#

The post One request, three implementations walks through it. The complete snippets are: