Skip to main content

AD Forge

Runtime-agnostic MCP server for data-driven solution architecture, with bundled Hermes skills.

Works with any MCP stdio client (Claude Desktop, Hermes, OpenClaw, etc.). The core logic is also importable as plain Python packages.

Authors: Amirthanathan R (amirth300324@gmail.com) and Dhivya GL (gldhivya1@gmail.com).

Project Structure

├── pyproject.toml              # Package metadata, deps, tool config
├── README.md                   # This file
├── CLAUDE.md                   # Guidance for Claude Code
├── .env.example                # Template for local env vars
├── Makefile                    # Common development targets
├── src/
│   └── adforge/
│       ├── __init__.py
│       ├── server.py           # MCP stdio server wiring
│       ├── models/             # Pydantic domain models
│       │   ├── problem.py
│       │   ├── solution.py
│       │   ├── sub_problem.py
│       │   ├── dag.py
│       │   └── cost.py
│       ├── persistence/        # SQLite repositories + migrations
│       │   ├── db.py
│       │   ├── migrations/
│       │   └── repositories/
│       ├── pricing/            # Cloud/role pricing provider wrappers
│       │   ├── aws.py
│       │   ├── azure.py
│       │   ├── gcp.py
│       │   ├── databricks.py
│       │   ├── roles.py
│       │   ├── cache.py (in repositories)
│       │   └── manager.py
│       ├── tools/              # MCP tool modules
│       │   ├── problem.py
│       │   ├── solution.py
│       │   ├── decompose.py
│       │   ├── cost.py
│       │   └── solution_cost.py
│       ├── prompts/            # MCP prompt modules
│       │   └── problem_decomposition.py
│       └── utils/
│           └── logging.py
├── skills/
│   └── solution-architect/
│       └── SKILL.md            # Hermes skill for architecture work
└── tests/

Quick Start

Install dependencies (uses uv or pip):

uv pip install -e ".[dev]"
# or
pip install -e ".[dev]"

Run the server manually:

python -m adforge.server
# or
adforge-mcp

Run tests:

uv run pytest tests/ -q

Workflow

  1. Capture a problem — create_problem(title, description, tags_csv).
  2. Decompose it — use the problem_decomposition prompt, then call decompose_problem(...) to create sub-problems and a DAG.
  3. Create a solution — create_solution(problem_id, title, body).
  4. Attach costs — attach_cost_to_solution(...) for each service/role/region.
  5. Summarize — summarize_solution_cost(solution_id).
  6. Review — add_solution_comment, add_solution_review, update_solution_status.

Pricing Sources

  • aws — public AWS Price List Query API (us-east-1), no credentials required.
  • azure — Azure Retail Prices API, no credentials required.
  • gcp / databricks — stub providers; supply manual_rate in parameters_json.
  • role — public/free role-pricing defaults; override with manual_rate.

Hermes Skill

The skills/solution-architect/SKILL.md is a Hermes-compatible skill. To use it:

  • Copy or symlink it into ~/.hermes/skills/solution-architect/SKILL.md, or
  • Keep it in-repo and load it directly if your agent supports in-repo skills.

MCP Configuration

Add to your MCP client config:

{
  "mcpServers": {
    "adforge": {
      "command": "uvx",
      "args": ["adforge"]
    }
  }
}

Or for local development:

mcp_servers:
  adforge:
    command: "uv"
    args: ["run", "python", "-m", "adforge.server"]

Environment Variables

Copy .env.example to .env and adjust:

  • ADFORGE_DB_PATH — SQLite file path.
  • ADFORGE_CACHE_TTL — pricing cache TTL in seconds.
  • AWS_PRICING_REGION — AWS region for pricing queries.
  • LOG_LEVEL, MCP_SERVER_NAME.

Metadata

Release files for adforge 0.1.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for adforge 0.1.2
File Size Uploaded Provenance Actions
adforge-0.1.2.tar.gz 99.2 kB Without provenance Details for adforge-0.1.2.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for adforge 0.1.2
File Interpreter ABI Platform Actions
adforge-0.1.2-py3-none-any.whl Python 3 none any Details for adforge-0.1.2-py3-none-any.whl

Total release size: 134.8 kB

Release files / adforge-0.1.2.tar.gz

Download URL adforge-0.1.2.tar.gz
Size 99.2 kB
Tags Source
SHA-256 checksum
How to use checksums
28096dbb56506f6d95a97044c9b42a476ed441dd6e06797dc5c3ea44dc50942c
BLAKE2b-256 checksum
How to use checksums
e605267fd182354f6065d9e5aa042965eab38c593a8ba20afe3be8970de999c7
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.9.7

Release files / adforge-0.1.2-py3-none-any.whl

Download URL adforge-0.1.2-py3-none-any.whl
Size 35.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
6f50d338bc5f74e16a11b4fb013156366cb200583be3dd17a9606193e926ed15
BLAKE2b-256 checksum
How to use checksums
a9bfd4babbb86cefe744e6503600deb4e68315ba34a38e5366e8c5eb1b825833
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.9.7

Security for adforge 0.1.2

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page