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
- Capture a problem —
create_problem(title, description, tags_csv). - Decompose it — use the
problem_decompositionprompt, then calldecompose_problem(...)to create sub-problems and a DAG. - Create a solution —
create_solution(problem_id, title, body). - Attach costs —
attach_cost_to_solution(...)for each service/role/region. - Summarize —
summarize_solution_cost(solution_id). - 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_rateinparameters_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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.