MCP Verified Agent Loop

A small, public engineering showcase for MCP, AI-agent tooling, verification gates, and human-in-the-loop review.

This project demonstrates the workflow I use when working with AI coding agents:

inspect codebase
→ plan
→ implement through bounded tools
→ lint / syntax / tests
→ inspect diff
→ human approval
→ audit trail

The important part is not that an agent can write code. The important part is that its capabilities are bounded and its changes are verifiable.

What this demonstrates

• Model Context Protocol (MCP) over stdio

• Tool-connected agent workflow

• Sandboxed repository access

• Path traversal protection

• Protected-path rules

• Bounded file writes

• No generic shell tool

• Allowlisted verification commands

• Test gates before approval

• Git diff inspection

• Human approval

• JSON audit trail

• Cross-platform TypeScript / Node.js implementation

• CI that runs the entire verified demo without API keys

Related MCP server: Hoplon

Architecture

flowchart LR
  A[Agent / Deterministic Planner] -->|MCP stdio| B[Workspace MCP Server]
  B --> C[Inspect]
  B --> D[Write]
  B --> E[Verify]
  B --> F[Diff]
  C --> G[Sandbox]
  D --> G
  E --> G
  F --> G
  F --> H[Human Approval]
  A --> I[Audit Trail]
  H --> I

See docs/architecture.md for the trust boundaries and design choices.

MCP tools

The server intentionally does not expose arbitrary shell execution.

Run it

Requirements:

• Node.js 22+

• Git

npm install
npm run verify

For an interactive human-approval prompt:

npm run demo

For CI / non-interactive demonstration:

npm run demo -- --approve

What the demo agent does

The demo starts from a clean fixture repository that already contains a titleCase utility.

Task:

Add a production-friendly slugify(value) helper and tests without breaking titleCase.

The agent then:

1. lists the repository through MCP;

2. reads the relevant source and package file;

3. searches for an existing slugify;

4. produces a change plan;

5. writes source and tests through MCP;

6. runs fixed syntax verification;

7. runs tests;

8. asks the MCP server for the git diff;

9. requires approval;

10. writes an audit record.

The demo workspace is isolated under .agent-workspace/ and is rebuilt from scratch each run.

Why no LLM API key is required

This public repo uses a deterministic planner so anyone can reproduce the workflow in CI.

The engineering proof is the boundary: MCP client/server integration, tool design, sandboxing, verification, diff review, approval, and auditability.

A model adapter can replace the planning policy without changing those boundaries.

Security

Read SECURITY.md.

Highlights:

• no arbitrary filesystem access

• no arbitrary shell command execution

• no environment-file access

• no employer/private code

• explicit human review before acceptance

Tech

TypeScript · Node.js 22 · MCP TypeScript SDK · Zod · Vitest · Git

Author

Yuttakan Phunkhlang
Software Engineer / Full-Stack Developer
Nuxt.js · Vue.js · TypeScript · Go · AI Coding Agents · MCP

• LinkedIn: https://www.linkedin.com/in/yuttakan-phunkhlang/

• GitHub: https://github.com/Yuttakarn2545

• Portfolio: https://personal-eosin-omega.vercel.app