AuxiScaffold

Generate production-ready Model Context Protocol (MCP) server scaffolds from a plain-English description — in under 90 seconds.

pip install auxiscaffold
auxiscaffold new "finance reconciliation server with bank statement matcher and GL reconciler"

---

Demo & Resources

Resource	Link
🎬 Demo Video	Watch on Google Drive
📊 Presentation (PPT)	Open in Google Slides

---

Executive Summary

AuxiScaffold is a developer CLI tool — think create-react-app, but for MCP servers.

You describe what your server should do in plain English. AuxiScaffold analyses the description with Claude AI, extracts a structured set of tools, and renders a fully working, production-ready Python project from versioned Jinja2 templates — deterministic, consistent, and ready to run.

It eliminates all the repetitive boilerplate that every MCP server project starts with: server setup, tool registration, Pydantic models, tests, documentation, CI pipelines, and configuration. Developers skip straight to writing business logic.

---

Problem Statement

Building an MCP server from scratch today means writing the same boilerplate every single time:

What needs to exist	Who currently writes it
Server entry point + FastMCP wiring	You
Tool registration + parameter schemas	You
Pydantic request / response models	You
Per-tool test stubs	You
Dockerfile + docker-compose	You
GitHub Actions CI pipeline	You
Architecture & API docs	You
.env config, .gitignore	You

Every new MCP project starts with hours of this scaffolding before a single line of domain logic is written. There is no standard layout, no consistency between projects, and no tooling to evolve the project after initial creation (add a tool, rename a tool, regenerate docs).

---

Solution

AuxiScaffold solves this with a pipeline that keeps the LLM away from code generation:

Plain-English description
         │
         ▼
  Domain Analyzer (Claude)        ← Structured extraction via tool_use, never free-form code
         │
         ▼
  MCPServerSpec (Pydantic)         ← Validates tool names, parameter types, return types
         │
         ▼
  Template Engine (Jinja2)         ← Deterministic rendering with StrictUndefined
         │
         ▼
  Generated project on disk        ← src-layout, per-tool files, CI, docs, tests

The LLM never writes code. It only fills in a structured JSON schema. All source files come from versioned Jinja2 templates bundled with the package — predictable, reviewable, and upgradeable.

---

Features

Feature	Description
Domain Analyzer	Extracts tools, parameters, and return types from plain English using Claude tool_use
Scaffold Generator	Renders a complete src/-layout MCP server project — 29+ files — from a single command
Smart add-tool	Context-aware: scaffolds a stub, or generates a full implementation via Claude if the tool already exists
remove-tool	Removes a tool and all its related files, with a confirmation guard
evolve	AI-driven project evolution — analyses your project, proposes additions/removals, applies with confirmation
ask (Auxi)	Project-aware AI assistant — asks about your own codebase using live context
Rename Tool	Renames a tool across all files — source, tests, models, imports — with rename-tool
README Generator	Regenerates the project README from the saved spec after any change
Intelligent Requirement Validation	Before calling the API, Claude assesses whether your description (new) or requirement (evolve) is specific enough — and asks up to 4 targeted follow-up questions if not. Answers are merged into the description automatically.
Input Validation	Rejects empty or symbol-only descriptions before calling the API
Duplicate Prevention	Prevents duplicate tool names in add-tool and rename-tool
Doctor	5-section health check: environment, project structure, per-tool status, tests, documentation + scored summary
Run Shortcuts	task dev,task run, task test — like npm run dev — in every generated project

---

Requirements

• Python 3.10+ — check with python --version
• An Anthropic API key — Claude powers the domain analysis

---

Complete Setup Guide (Step by Step)

Follow every step in order. By the end you will have a running MCP server visible in the MCP Inspector.

---

Step 1 — Open a terminal and navigate to your working folder

# Windows — open Command Prompt (cmd) or PowerShell
cd C:\Users\YourName\Projects

Pick any folder where you want the generated project to be created.

---

Step 2 — Install AuxiScaffold

# Latest preview (Test PyPI)
pip install -i https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ auxiscaffold

If auxiscaffold is not recognised after install, Python's user scripts folder is not on your PATH. Run the following to find the correct path, then add it to your system environment variables:

python -c "import sysconfig; print(sysconfig.get_path('scripts'))"

Take the output (e.g. C:\Users\YourName\AppData\Roaming\Python\Python312\Scripts), and add that full path to your PATH environment variable. Then reopen the terminal.

---

Step 3 — Set your Anthropic API key

# Windows (Command Prompt)
set ANTHROPIC_API_KEY=sk-ant-api03-your-key-here

# Windows (PowerShell)
$env:ANTHROPIC_API_KEY="sk-ant-api03-your-key-here"

# macOS / Linux
export ANTHROPIC_API_KEY=sk-ant-api03-your-key-here

Get a key at console.anthropic.com.

---

Step 4 — Run the health check

auxiscaffold doctor

This verifies:

• Python version ≥ 3.10
• ANTHROPIC_API_KEY is set
• All required packages are installed
• All bundled templates are present

If doctor passes → move to Step 5. If it reports a missing PATH issue, see the note in Step 2.

---

Step 5 — Create your MCP server project

auxiscaffold new "A finance reconciliation MCP server that matches bank statement transactions with internal records, reconciles general ledger balances against subledgers, validates intercompany transactions between entities, identifies discrepancies and unmatched entries, calculates variances, and generates audit-ready reconciliation reports with detailed exception summaries."

AuxiScaffold will:

1. Send your description to Claude to extract tool names, parameters, and return types
2. Validate the spec with Pydantic
3. Render all project files to disk

The generated folder structure looks like this:

finance_reconciliation_server/
├── src/
│   └── finance_reconciliation_server/
│       ├── __init__.py
│       ├── server.py              # FastMCP entry point
│       ├── config.py              # Env-based config (reads .env)
│       ├── tools/
│       │   ├── __init__.py
│       │   ├── match_bank_transactions.py
│       │   ├── reconcile_gl_to_subledger.py
│       │   ├── validate_intercompany_transactions.py
│       │   └── generate_reconciliation_report.py
│       ├── models/
│       │   ├── requests.py        # Pydantic input models per tool
│       │   └── responses.py       # Pydantic output models per tool
│       ├── services/              # Business logic layer
│       └── utils/                 # Shared helpers
├── tests/
│   ├── test_match_bank_transactions.py
│   ├── test_reconcile_gl_to_subledger.py
│   └── fixtures/
├── docs/
│   ├── architecture.md
│   ├── tools.md
│   └── api.md
├── examples/
├── .github/workflows/ci.yml
├── pyproject.toml
├── Makefile
├── Dockerfile
├── docker-compose.yml
├── requirements.txt
├── CHANGELOG.md
└── .env.example

You can open this folder in Visual Studio Code (code finance_reconciliation_server) to browse and edit the structure.

---

Step 6 — Add, implement, or evolve tools (optional)

Add a new tool scaffold:

auxiscaffold add-tool "validate duplicate invoices" --dir finance_reconciliation_server

add-tool is context-aware — it detects the current state of the tool and acts accordingly:

State	What it does
Tool doesn't exist yet	Scaffolds stub file + test + model entries
Tool exists as scaffold (NotImplementedError)	Generates a full implementation via Claude and injects it
Tool already implemented	Regenerates the implementation based on an updated description

Remove a tool:

auxiscaffold remove-tool validate_duplicate_invoices --dir finance_reconciliation_server

Removes the tool file, test file, and all references from __init__.py, server.py, and models.

Evolve the whole project with a new requirement:

auxiscaffold evolve "add support for multi-currency reconciliation" --dir finance_reconciliation_server

AuxiScaffold analyses the existing project, proposes a plan (tools to add/remove/update, dependencies to change), shows it to you for confirmation, then applies it.

---

Step 7 — Ask Auxi about your project (optional)

Auxi is a project-aware AI assistant that reads your live codebase before answering:

auxiscaffold ask "How does the GL reconciliation tool handle unposted transactions?" --dir finance_reconciliation_server
auxiscaffold ask "What would I need to add to support multi-currency?" --dir finance_reconciliation_server

---

Step 8 — Rename a tool (optional)

auxiscaffold rename-tool validate_duplicate_invoice validate_payments --dir finance_reconciliation_server

Renames the tool file, test file, and all imports across the project. Special characters are auto-sanitised to snake_case.

---

Step 9 — Regenerate the README (optional)

After adding or renaming tools, regenerate the project's own README:

auxiscaffold generate-readme --dir finance_reconciliation_server

---

Step 10 — Explore all commands

auxiscaffold --help
auxiscaffold new --help
auxiscaffold add-tool --help
auxiscaffold evolve --help
auxiscaffold ask --help

---

Step 11 — Set up the generated project

Navigate into the generated project folder and create a virtual environment:

cd finance_reconciliation_server

# Windows
python -m venv .venv
.venv\Scripts\pip install -e ".[dev]"

# macOS / Linux
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

.[dev] installs the project itself plus pytest and taskipy (for the run shortcuts).

---

Step 12 — Run the MCP server and open the Inspector

The MCP Inspector is a browser UI where you can visualise all your tools, call them with test inputs, and see the responses — without needing Claude Desktop.

Prerequisite for the Inspector UI: task dev, make dev, and tasks.ps1 dev all use MCP Inspector via npx, which requires Node.js to be installed on your system. Get it at nodejs.org. If you prefer not to install Node.js, skip dev and use task run to start the server for Claude Desktop, or run python -m pytest to test tools directly.

Option A — tasks.ps1 (Windows, no extra tools needed)

.\tasks.ps1 dev     # starts server + opens MCP Inspector in browser
.\tasks.ps1 run     # starts server only (no browser, for Claude Desktop)
.\tasks.ps1 test    # runs all pytest tests

Option B — task shortcuts (any OS, after pip install -e ".[dev]")

task dev     # starts server + opens MCP Inspector in browser
task run     # starts server only (no browser, for Claude Desktop)
task test    # runs all pytest tests

Option C — Makefile (macOS / Linux)

make dev
make run
make test

Option D — direct commands (any OS)

# With Inspector (requires Node.js)
npx @modelcontextprotocol/inspector python "src/<package_name>/server.py"

# Without Inspector (raw stdio server)
python "src/<package_name>/server.py"

The MCP Inspector opens at http://localhost:6274 (or similar). You will see every tool listed with its input schema. Click a tool, fill in test values, and call it — live.

---

Step 13 — Connect to Claude Desktop (optional)

To use your MCP server tools directly inside Claude Desktop, add it to the config file.

Config file location:

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "finance_reconciliation_server": {
      "command": "C:\\path\\to\\finance_reconciliation_server\\.venv\\Scripts\\python.exe",
      "args": ["-m", "finance_reconciliation_server.server"],
      "cwd": "C:\\path\\to\\finance_reconciliation_server"
    }
  }
}

Restart Claude Desktop — your tools will appear in the tool list automatically.

---

Commands Reference

Command	Description
auxiscaffold --version / -v	Show the installed version and exit
auxiscaffold new DESCRIPTION	Generate a new MCP server project from a plain-English description
auxiscaffold add-tool DESCRIPTION	Add, implement, or update a tool (context-aware 3-state)
auxiscaffold remove-tool NAME	Remove a tool and all its related files
auxiscaffold rename-tool OLD NEW	Rename a tool across all project files
auxiscaffold evolve REQUIREMENT	AI-driven evolution of the whole project based on a new requirement
auxiscaffold ask QUESTION	Ask Auxi, the project-aware AI assistant, about your codebase
auxiscaffold generate-readme	Regenerate the project README from the saved spec
auxiscaffold doctor	Comprehensive environment + project health check

new

auxiscaffold new "invoice processing server with pdf extractor and line item parser"
auxiscaffold new "my server" --output-dir ./my_project
auxiscaffold new "my server" --overwrite        # replace existing directory

Before analysing your description, AuxiScaffold runs an intelligent completeness check. If your description is too vague to design 2–6 meaningful tools, Claude asks up to 4 targeted follow-up questions. Your answers are merged into the description automatically — no retyping needed.

$ auxiscaffold new "invoice server"

⚠ Your description needs a bit more detail before we can generate a great server.

1. What specific invoice operations should the server support?
   Your answer []: extract line items from PDF, validate VAT numbers, post to ERP

2. What data sources or systems does the server integrate with?
   Your answer []: SAP for ERP posting, PDF files as input
...
✓ Description enriched with your answers.

If your description is already detailed, the check completes silently and generation proceeds immediately.

Option	Default	Description
--output-dir / -o	server name	Output directory
--overwrite	false	Replace existing directory

add-tool

Context-aware — detects the tool's current state and acts accordingly:

# First call: scaffolds a stub
auxiscaffold add-tool "validate duplicate invoices" --dir finance_reconciliation_server

# Second call (stub exists): generates a full Claude implementation
auxiscaffold add-tool "validate duplicate invoices" --dir finance_reconciliation_server

# Or update with a revised description
auxiscaffold add-tool "validate duplicate invoices with tolerance threshold" --dir finance_reconciliation_server

Option	Default	Description
--dir / -d	.	Path to existing project

remove-tool

auxiscaffold remove-tool validate_duplicate_invoices --dir finance_reconciliation_server
# skip confirmation prompt:
auxiscaffold remove-tool validate_duplicate_invoices --yes --dir finance_reconciliation_server

Option	Default	Description
--dir / -d	.	Path to existing project
--yes / -y	false	Skip confirmation prompt

evolve

auxiscaffold evolve "add support for multi-currency reconciliation" --dir finance_reconciliation_server

Before planning changes, AuxiScaffold runs an intelligent requirement clarity check. If your requirement is too broad (e.g. "improve it", "make it better"), Claude asks up to 3 targeted questions to clarify what specifically should change. Answers are merged into the requirement automatically.

$ auxiscaffold evolve "improve compliance and validation" --dir finance_reconciliation_server

⚠ Your requirement needs a bit more detail before we can plan a precise change.

1. What specific compliance standards should the server validate against?
   Your answer []: HIPAA and HL7 FHIR

2. Which operations need validation — input, output, or both?
   Your answer []: both
...
✓ Requirement enriched with your answers.

Runs a 6-step pipeline: load spec → check consistency → analyse with Claude → show plan → confirm → apply.

Option	Default	Description
--dir / -d	.	Path to existing project

ask

auxiscaffold ask "How does GL reconciliation handle unposted transactions?" --dir finance_reconciliation_server
auxiscaffold ask "What would I need to add for multi-currency support?" --dir finance_reconciliation_server

Auxi reads your live spec, source files, and tests before answering — context-aware, not generic.

Option	Default	Description
--dir / -d	.	Path to existing project

rename-tool

auxiscaffold rename-tool old_name new_name --dir finance_reconciliation_server

Option	Default	Description
--dir / -d	.	Path to existing project

generate-readme

auxiscaffold generate-readme --dir finance_reconciliation_server

doctor

auxiscaffold doctor
auxiscaffold doctor --dir finance_reconciliation_server   # inspect a specific project

Runs a scored 5-section health check:

Section	What it checks
Environment	Python ≥ 3.10, virtual env, API key, required packages, templates, Git
Project	.auxiscaffold.json validity, scaffold version, required directories and core files
Tool Health	Per-tool: file exists, stub vs implemented, registered in __init__.py, model coverage
Tests	Per-tool test file present, fixtures directory, stub-only guard detection
Documentation	README present with all tools referenced, docs/api.md, docs/architecture.md

Outputs a progress-bar score per section (green ≥ 90%, yellow ≥ 70%, red < 70%) plus prioritised recommendations.

---

Run Shortcuts (in generated projects)

Every project generated by AuxiScaffold includes a tasks.ps1 (Windows), taskipy tasks, and a Makefile so you can run common actions with short commands — just like npm run dev.

Command	Platform	What it does
.\tasks.ps1 dev	Windows (no extra tools)	Start server + open MCP Inspector in browser
.\tasks.ps1 run	Windows (no extra tools)	Start raw server (no browser, for Claude Desktop)
.\tasks.ps1 test	Windows (no extra tools)	Run pytest
.\tasks.ps1 install	Windows (no extra tools)	pip install -e ".[dev]"
task dev	Any OS (needs pip install -e ".[dev]")	Start server + open MCP Inspector
task run	Any OS	Start raw server
task test	Any OS	Run pytest
task lint	Any OS	Quick syntax check
make dev	macOS / Linux	Start server + open MCP Inspector
make run	macOS / Linux	Start raw server
make test	macOS / Linux	Run pytest

task is provided by taskipy — installed with pip install -e ".[dev]".

---

Development (contributing to AuxiScaffold itself)

git clone https://github.com/auxiliobits/auxiscaffold
cd auxiscaffold

python -m venv .venv
.venv\Scripts\pip install -e ".[dev]"     # Windows
# source .venv/bin/activate && pip install -e ".[dev]"   # macOS/Linux

auxiscaffold doctor    # verify everything is set up

---

Sample Input & Output

Example 1 — auxiscaffold new

Input:

auxiscaffold new "A finance reconciliation MCP server that matches bank statement transactions with internal GL records, reconciles general ledger balances against subledgers, and generates audit-ready reconciliation reports."

Output:

✓ Analysing description with Claude AI...
✓ Extracted 4 tools · 14 parameters

  Tools identified:
    • match_bank_transactions
    • reconcile_gl_to_subledger
    • validate_intercompany_transfers
    • generate_reconciliation_report

✓ Rendered 29 files → finance_reconciliation_server/
✓ Done in 11.2s

Generated structure:

finance_reconciliation_server/
├── src/finance_reconciliation_server/
│   ├── server.py        ← FastMCP entry point, all tools registered
│   ├── tools/           ← one .py file per tool
│   └── models/          ← Pydantic request + response models
├── tests/               ← one test file per tool
├── docs/  examples/  .github/workflows/ci.yml
└── Makefile  Dockerfile  pyproject.toml  requirements.txt

---

Example 2 — auxiscaffold add-tool

Input:

auxiscaffold add-tool "validate duplicate invoices by amount and date" --dir finance_reconciliation_server

Output:

  Description: validate duplicate invoices by amount and date

  How would you like to create this tool?
    1. Scaffold only
    2. Scaffold + AI implementation

Select an option (1/2) [1]: 2

  Using your description as the business requirement:
  validate duplicate invoices by amount and date
  Press Enter to continue, or type a different requirement to override:

  ✓ Tool validate_duplicate_invoices scaffolded and implemented
    src/.../tools/validate_duplicate_invoices.py  (implementation injected)
    tests/test_validate_duplicate_invoices.py      (tests injected)
    server.py · __init__.py · models/              (updated)

---

Example 3 — auxiscaffold ask

Input:

auxiscaffold ask "How does the GL reconciliation tool handle unposted transactions?" --dir finance_reconciliation_server

Output:

  Auxi is reading your project...

  The reconcile_gl_to_subledger tool filters transactions by the
  posted flag before running balance matching. Entries where
  posted=False are excluded and surfaced separately in the
  exceptions list as UnmatchedEntry items with reason="unposted".

  To include unposted entries, add an include_unposted: bool
  parameter to the request model and remove the filter.

---

Example 4 — auxiscaffold doctor

Input:

auxiscaffold doctor --dir finance_reconciliation_server

Output:

  AuxiScaffold Doctor — finance_reconciliation_server

  Environment      ████████████  100%  ✓
  Project          ████████████  100%  ✓
  Tool Health      ██████████░░   83%  ⚠
  Tests            ████████████  100%  ✓
  Documentation    ████████████  100%  ✓

  Overall: 97%  ✓  Publication-ready

  Recommendations:
    ⚠  2 tools still have NotImplementedError stubs:
       • reconcile_gl_to_subledger
       • validate_intercompany_transfers
       Run: auxiscaffold add-tool <name> --dir . to implement them

---

Known Limitations

Limitation	Detail
Claude API required	All AI commands (new, add-tool option 2, evolve, ask) require an active ANTHROPIC_API_KEY. Scaffold-only operations (add-tool option 1, rename-tool, remove-tool, generate-readme) work without it.
Tool name length	Tool names are extracted by Claude and capped at ~40 characters in snake_case. Passing an extremely long sentence to add-tool may produce a shorter name than the full description.
Python 3.10+ only	Both the CLI and the generated projects require Python 3.10 or higher.
MCP Inspector requires Node.js	task dev / .\tasks.ps1 dev open the Inspector via npx. Without Node.js, use task run (Claude Desktop) or python -m pytest (testing) instead.
Stubs by default	auxiscaffold new scaffolds tool stubs with NotImplementedError. Use auxiscaffold add-tool to generate the AI implementation per tool.
Single-spec projects	Each project is backed by one .auxiscaffold.json spec. Multi-service monorepos are not yet supported.
Internet required	All Anthropic API calls require outbound HTTPS to api.anthropic.com.

---

License

MIT — © Auxiliobits

---

---

---

Built By

Name	GitHub
Sanya Sachdeva	@SanyaSachdeva05
Navdeep Singh	@NavdeepSingh1001

Built during the AuxiLab Founding Hackathon by Auxiliobits Technologies · AuxiLab Catalogue