# Technical Documentation: Arindam200/awesome-ai-apps
> βΉοΈ **Provenance:** Multi-Tier Ingestion Β· [CodeWiki Reference](https://codewiki.google/github.com/Arindam200/awesome-ai-apps)
### Overview (README.md)
# Awesome AI Apps [](https://awesome.re)
## π₯ Stay Updated with Daily AI Insight!
Get easy-to-follow weekly tutorials and deep dives on AI, LLMs, and agent frameworks. Perfect for developers who want to learn, build, and stay ahead with new tech. Subscribe our Newsletter!
[](https://mranand.substack.com/subscribe)
---
## Getting Started
### Prerequisites
- **Python 3.10+** (Python 3.11+ recommended for newer projects)
- **Git** for cloning the repository
- **Package Manager**: `pip` or `uv` (recommended for faster installs)
- **API Keys**: Most projects require API keys (see individual project READMEs)
### Quick Start
1. **Clone the repository**
```bash
git clone https://github.com/Arindam200/awesome-ai-apps.git
cd awesome-ai-apps
```
2. **Choose a project** and navigate to its directory
```bash
cd starter_ai_agents/agno_starter # Example: Start with Agno starter
```
3. **Set up environment variables**
```bash
cp .env.example .env # Copy example environment file
# Edit .env with your API keys
```
4. **Install dependencies**
```bash
# Using pip
pip install -r requirements.txt
# OR using uv (recommended - faster)
uv sync
# or
uv pip install -e .
```
5. **Run the project**
```bash
python main.py
# or for Streamlit apps
streamlit run app.py
```
## π€ Contributing
We welcome contributions from the community! Here's how you can help:
- π‘ **Add new projects**: Submit your own AI agent examples
- π§ **Fix issues**: Contribute code improvements and bug fixes
- π **Improve documentation**: Help make projects more accessible
- π **Report bugs** or suggest improvements via [GitHub Issues](https://github.com/Arindam200/awesome-ai-apps/issues)
**Before contributing:**
- Read our [Contributing Guidelines](CONTRIBUTING.md) for detailed information
- Check existing issues to avoid duplicates
- Follow the project structure and naming conventions
- Ensure your project includes a comprehensive README.md
**Important:** This project follows a [Contributor Code of Conduct](CODE_OF_CONDUCT.md). By participating, you agree to abide by its terms.
## π License
This repository is licensed under the [MIT License](./LICENSE). Feel free to use and modify the examples for your projects.
## π₯ Core Maintainers
This project is actively maintained by:
Arindam Majumder
Β·
Shivay Lamba
Β·
Amitesh Anand
For any questions, suggestions, or contributions, feel free to reach out to the maintainers.
## Thank You for the Support! π
[](https://star-history.dera.page/#Arindam200/awesome-ai-apps&Date)
---
### Mcp Ai Agents Mcp Toolbox Security Agent Docs ARCHITECTURE (`mcp_ai_agents/mcp_toolbox_security_agent/docs/ARCHITECTURE.md`)
# Architecture
## Components
| Component | Role |
|---|---|
| **agent-web** (FastAPI + Google ADK) | The user-facing app + shopping agent. The LLM is **pluggable** β Nebius Token Factory (Kimi-K2.6) by default via ADK's LiteLLM adapter, or Gemini (`AGENT_PROVIDER=gemini`). Loads Toolbox tools via the `toolbox-core` SDK. Lives **outside** the trust boundary, so the provider choice changes no security property. Gemini is still used for query embeddings (semantic search). |
| **MCP Toolbox** | The security control plane. Serves curated tools over HTTP/MCP; binds identity from tokens; holds the DB credentials; emits OpenTelemetry. |
| **PostgreSQL** | System of record: users, product catalog (price/stock), carts, orders. Accessed only via least-privilege roles. |
| **MongoDB (Atlas Local)** | Vector/semantic product search over pre-computed Gemini embeddings (`$vectorSearch`). |
| **Keycloak** | OIDC identity provider (local). Issues the JWTs Toolbox validates. Swapped for Google Sign-In in production. |
| **OTel Collector + Jaeger** | Traces/metrics pipeline. |
## The trust boundary
```
βββββββββββββββββββββββββββββββββββββββ
login β agent-web (FastAPI) β
alice β ββ Google ADK + Gemini agent β tool calls (HTTP/MCP)
bob β ββ deterministic demo endpoints ββββββββββββββββ
carol ββββββββββββββββ¬βββββββββββββββββββββββ keycloak_token (JWT)
β embeddings (Gemini) β
βΌ βΌ
google-genai ββββββββββββββββββββββ
β MCP TOOLBOX β βββ TRUST BOUNDARY
Keycloak (OIDC) ββissues JWTβββββββββββββββββββΆ β β’ custom tools β
β² β β’ authN params β
βββ agent-web logs users in (server-side) β β’ authRequired β
β β’ parameterized β
β β’ least-priv roles β
βββββ€ββββββββββββ€ββββββ
parameterized SQL ($1) β β $vectorSearch
role: toolbox_app/adminβΌ βΌ
βββββββββββββ ββββββββββββ
β PostgreSQLβ β MongoDB β
βββββββββββββ ββββββββββββ
```
Everything to the left of the double line is **untrusted** with respect to the
data: the LLM, its prompt, and the tool arguments it produces. All enforcement
happens at Toolbox and in the database.
## Request lifecycle (e.g. "show my orders")
1. The browser calls agent-web; the server attaches the signed-in user's JWT.
2. The agent (or a deterministic endpoint) calls the Toolbox tool `list_my_orders`.
The token travels in the `keycloak_token` header. **No `username` is sent** β
the tool's schema doesn't have one.
3. Toolbox validates the JWT against the OIDC issuer (signature, issuer,
audience), extracts `preferred_username`, and binds it into the SQL parameter.
4. Toolbox runs `... WHERE u.username = $1` as the least-privilege `toolbox_app`
role, returns rows, and records a trace span.
5. A different user's data is unreachable: the model can't pass `username`, and
even a forged body value is ignored (the claim wins).
## Why polyglot (Postgres + Mongo)
Transactional integrity (orders, carts, prices, least-privilege roles, IAM) lives
in PostgreSQL; semantic search lives in MongoDB vector search. Toolbox presents
**one** secure gateway over both, joined by `sku`. This shows the control plane
generalizing across very different datastores β a realistic production shape.
## Local vs. GKE
| Concern | Local (compose) | GKE (`deploy/k8s/`) |
|---|---|---|
| Postgres source | `kind: postgres` + password | `kind: cloud-sql-postgres`, **no password** (IAM) |
| DB auth | role password in `.env` | Workload Identity KSAβGSA, IAM DB users |
| `tools.yaml` | bind-mounted file | mounted from a Secret |
| Secrets | `.env` | Secret Manager (CSI / External Secrets) |
| Network | compose bridge | NetworkPolicy: agentβToolboxβDB only |
| Telemetry | `--telemetry-otlp` β collector | `--telemetry-gcp` β Cloud Trace/Monitoring |
| Identity | local Keycloak | Google Sign-In (`authService: kind: google`) |
| Scaling | single container | HPA 2β10, built-in connection pooling |
The **tools, authenticated parameters, and roles are identical** across both β
only the `sources:` block changes (`deploy/k8s/tools.yaml` is generated from
`toolbox/tools.yaml`).
## Catalog data flow
`scripts/build_catalog.py` streams `grocery_store.inventory.json` (70 MB of
products with Gemini embeddings), assigns SKUs, and loads an **aligned** catalog
into Postgres (price/stock) and Mongo (embeddings + `sku`), then builds the
`vector_index`. This guarantees a product returned by vector search exists, with
an authoritative price, in Postgres.
---
### Mcp Ai Agents Mcp Toolbox Security Agent Docs ARCHITECTURE DIAGRAM (`mcp_ai_agents/mcp_toolbox_security_agent/docs/ARCHITECTURE_DIAGRAM.md`)
# Technical Architecture β MCP Toolbox E-Commerce Security Demo
The diagram below shows every layer of the system and how **MCP Toolbox acts as
the security control plane** between the untrusted LLM layer and the databases.
Annotated numbers correspond to the ten security mechanisms documented in
[SECURITY.md](SECURITY.md).
```
/* Detailed source-code truncated for AI context efficiency. */
```
---
## Security mechanism quick-reference
| # | Mechanism | Where enforced | What it prevents |
|---|---|---|---|
| 1 | **Custom named tools only** β no `execute_sql` | `tools.yaml` (10 tools) | Arbitrary query power; attack surface = tool list |
| 2 | **Authenticated parameters** β `username` from JWT claim | `tools.yaml` `authServices` | Model requesting another user's data |
| 3 | **Authorized invocations** β `authRequired:[keycloak_admin]` | `tools.yaml` admin tools | Non-admins calling `view_all_orders` / `update_inventory` |
| 4 | **SDK bound parameters** β `store_region` fixed by app | `agent/agent.py` `bound_params` | Model choosing tenant / region |
| 5 | **Parameterized queries** β `$1 β¦ $n` everywhere | `tools.yaml` all SQL stmts | SQL injection |
| 6 | **Least-privilege DB roles** β `toolbox_app` / `toolbox_admin` | `db/postgres/01_roles.sql` | Blast radius of a compromised tool |
| 7 | **IAM / Workload Identity** β `cloud-sql-postgres`, no password | `deploy/k8s/tools.yaml` | DB password in the cluster |
| 8 | **Secrets via env-var interpolation** β `${VAR}` in `tools.yaml` | `tools.yaml` + `.env` / Secret Manager | Credentials in source code |
| 9 | **Full observability** β OTLP on every tool call | `--telemetry-otlp` / `--telemetry-gcp` | Silent misuse; every call is an audited trace |
| 10 | **Network hardening** β `--allowed-hosts`; K8s `NetworkPolicy` | `deploy/k8s/networkpolicy.yaml` | Agent reaching DBs directly; SSRF |
> **Key insight:** Everything to the left of the Toolbox boundary (the LLM,
> its prompt, its tool arguments) is treated as **untrusted input**.
> All enforcement happens *inside* Toolbox and in the database β below the agent,
> making misuse structurally impossible rather than just discouraged.
---
### Mcp Ai Agents Mcp Toolbox Security Agent Docs RUNBOOK (`mcp_ai_agents/mcp_toolbox_security_agent/docs/RUNBOOK.md`)
# Live demo runbook
A ~6β8 minute talk demo. Every step has a UI action **and** a CLI fallback you
can run if a slide or click fails.
## Before you go on stage
```bash
scripts/bootstrap_local.sh # ~3β5 min: build, start, seed catalog
scripts/verify_security.sh # confirm all 11 checks pass
```
Open tabs: **http://localhost:8080** (UI) and **http://localhost:16687** (Jaeger).
For the live chat, set `NEBIUS_API_KEY` (Kimi-K2.6 agent) and `GOOGLE_API_KEY`
(Gemini embeddings for semantic search) in `deploy/compose/.env`, then
`docker compose ... up -d agent-web`. Otherwise use the deterministic buttons,
which need no API key.
Reset demo state any time:
```bash
docker compose -f deploy/compose/docker-compose.yaml --env-file deploy/compose/.env \
run --rm catalog # re-seeds alice's cart + bob's order
```
## The script
**1 β Frame it (30s).** "An agent that can touch a production database is a
security problem. The usual answer is an MCP server with `execute_sql` β the
agent can run anything. We did the opposite: MCP Toolbox gives the agent narrow
tools and becomes the trust boundary." Show `docs/ARCHITECTURE.md` diagram.
**2 β Shop as alice (1m).** Sign in as **alice**. In chat: *"find me some dark
chocolate"* β *"add two of the first one"* β *"check out"*. (No API key? Use the
cart/refresh buttons after running the CLI below.) Point out: the agent passed a
`sku`, never a price or a username.
**3 β Per-user scoping (1m).** Click **Refresh cart / Refresh orders** β alice
sees only her data. Sign in as **bob**: different cart, different orders. Nothing
in the agent or the request said "alice" or "bob" β Toolbox derived it from the
login token.
**4 β The block (1.5m, the centerpiece).** Back as **alice**, in *Cross-user
access test* enter bob's order id (**1**) β **Read order details**. Result: a red
**Blocked** banner, zero rows. "She asked for order 1. Toolbox ran the query as
*her*. `username` is bound from her token β she can't pass it, can't forge it."
CLI fallback / proof:
```bash
# inside the stack so the token issuer matches:
docker compose -f deploy/compose/docker-compose.yaml --env-file deploy/compose/.env \
exec -T agent-web python3 - <<'PY'
import urllib.request,urllib.parse,json
def tok(u):
d=urllib.parse.urlencode({"client_id":"grocery-agent","grant_type":"password","username":u,"password":u+"123"}).encode()
return json.load(urllib.request.urlopen("http://keycloak:8080/realms/grocery/protocol/openid-connect/token",d))["access_token"]
def call(t,p,h):
r=urllib.request.Request(f"http://toolbox:5000/api/tool/{t}/invoke",json.dumps(p).encode(),{"Content-Type":"application/json",h[0]:h[1]})
return urllib.request.urlopen(r).read().decode()
print("alice -> bob's order:", call("get_order_details",{"order_id":1},("keycloak_token",tok("alice"))))
print("bob -> bob's order:", call("get_order_details",{"order_id":1},("keycloak_token",tok("bob"))))
PY
```
**5 β Why it's impossible, not just unlikely (1m).** Click **Show tool schemas**.
Contrast: the Toolbox manifest lists `username` annotated `authServices:[keycloak]`,
but the model's function signature is `view_cart()` / `add_to_cart(quantity, sku)`
β **no username**. "The model can't pass what isn't in its schema."
**6 β Admin gating (1m).** As **alice**, click **view_all_orders** β denied. Sign
in as **carol** (admin) β it returns every order. "Same tool, different token.
Only carol's token carries the `grocery-admin` audience β and that's role-driven
in Keycloak, she can't self-grant it."
**7 β It's all audited (45s).** Open **Jaeger** (http://localhost:16687), service
`toolbox`. Show the spans for the calls you just made β including the blocked one
(a successful, audited tool call that returned zero rows, not a silent drop).
**8 β Land the plane (30s).** Recap with `docs/SECURITY.md`: authenticated
parameters, authorized invocations, parameterized queries, least-privilege roles,
IAM/Workload Identity, observability. "Toolbox is the control plane. The agent is
outside the trust boundary β by construction." Show `deploy/k8s/` for the GKE
shape (Workload Identity = no DB password at all).
## One-command proof (if you only have 60 seconds)
```bash
scripts/verify_security.sh
```
11 green checks: authenticated params, the cross-user block, no-token rejection,
admin allow/deny, SQL-injection-as-literal, and three least-privilege denials.
## Troubleshooting
- **Toolbox restarting** β it inits sources + OIDC eagerly; it converges once
Keycloak's realm is imported (`restart: on-failure`). Give it ~60s after first
boot. `docker compose ... logs toolbox`.
- **Chat returns 503** β `NEBIUS_API_KEY` isn't set (or `GOOGLE_API_KEY` if
`AGENT_PROVIDER=gemini`); the security demo still works without it.
- **Chat works but search fails** β semantic search needs `GOOGLE_API_KEY`
(Gemini query embeddings); cart/checkout/orders still work without it.
- **Token rejected by Toolbox** β only mint tokens *inside* the network
(`keycloak:8080`); a host-minted token (`localhost:8085`) has a different
issuer. `scripts/get_token.sh` is for inspecting claims, not calling Toolbox.
- **Port already in use** β published host ports are 8080/5055/8085/16687/8899/
5544/27117; change them in `deploy/compose/docker-compose.yaml` if needed.
---
### Mcp Ai Agents Mcp Toolbox Security Agent Docs SECURITY (`mcp_ai_agents/mcp_toolbox_security_agent/docs/SECURITY.md`)
# Security model β how MCP Toolbox constrains the agent
The agent is treated as **untrusted**. Ten mechanisms, layered, ensure that no
prompt, jailbreak, or malformed tool argument lets it exceed its authority. Each
is implemented in this repo and verified by `scripts/verify_security.sh`.
## Mechanism map
| # | Mechanism | Where | What it stops |
|---|---|---|---|
| 1 | **Custom tools, not `execute_sql`** | `toolbox/tools.yaml` β only 10 named tools; the Mongo vector index/path are hardcoded | The agent never has arbitrary query power; the attack surface is the tool list |
| 2 | **Authenticated parameters** | `tools.yaml` β `username` carries `authServices:[{name: keycloak, field: preferred_username}]` | The model can't request another user's data; `username` isn't even in its tool schema |
| 3 | **Authorized invocations** | `tools.yaml` β admin tools have `authRequired:[keycloak_admin]` | Non-admins can't call `view_all_orders` / `update_inventory` |
| 4 | **Bound parameters (SDK)** | `agent/agent.py` β `bound_params={"store_region": ...}` | The model can't choose the tenant/region; it's fixed by the app |
| 5 | **Parameterized queries** | `tools.yaml` β every statement uses `$1..$n` (no string interpolation) | SQL injection; tool args are values, never SQL |
| 6 | **Least-privilege DB roles** | `db/postgres/01_roles.sql` β `toolbox_app` / `toolbox_admin`, one per source | A compromised tool can't DROP/UPDATE-catalog/DELETE-orders |
| 7 | **IAM / Workload Identity** | `deploy/k8s/` β `cloud-sql-postgres` with no password; KSAβGSA | No DB password exists in the cluster at all |
| 8 | **Secrets handling** | `${ENV}` in `tools.yaml`; `.env` (local) / Secret Manager (GKE) | Credentials never reach the model and aren't hardcoded |
| 9 | **Observability** | `--telemetry-otlp` / `--telemetry-gcp`; `observability/` | Every tool call is an audited, traced event |
| 10 | **Network hardening** | `--allowed-hosts` / `--allowed-origins`; `deploy/k8s/networkpolicy.yaml` | Only agentβToolboxβDB; the agent can't reach the DB directly |
## The headline: authenticated parameters (#2)
The `view_cart` tool is defined with a single parameter that the model never sees:
```yaml
parameters:
- name: username
type: string
authServices:
- name: keycloak
field: preferred_username # taken from the verified token, not the model
```
Verified behavior (from the running stack):
- The model-facing signature is `view_cart() -> str` β **no `username`**.
(`add_to_cart(quantity, sku)`, `get_order_details(order_id)` β same story.)
- Calling `view_cart` with a body of `{"username":"bob"}` while presenting
alice's token **still returns alice's cart**. The forged value is ignored; the
claim wins.
- Calling it with **no token β HTTP 401** ("error parsing authenticated
parameter"). Identity isn't optional.
- `get_order_details(order_id=)` as alice β **zero rows**. Ownership is in
the `WHERE` clause against the authenticated username; it can't be bypassed.
This is the difference between *asking the model nicely* and *making it
impossible*: identity is resolved deterministically by the server, below the
agent.
## Admin gating is role-driven, not request-driven (#3)
`view_all_orders` and `update_inventory` use `authRequired: [keycloak_admin]`,
whose audience is `grocery-admin`. In Keycloak, only **carol** holds the
`grocery-admin` client role, so the built-in *audience-resolve* mapper adds that
audience to her token automatically. alice/bob can't obtain it β even requesting
the scope explicitly is rejected ("Invalid scopes"). Verified: alice β 401,
carol β 200.
> **Honest caveat (the confused-deputy lesson):** bound parameters (#4) and the
> app's choice of *which* token/header to send are trusted to the application
> layer. Toolbox stops the *model*; your app process must still be trustworthy.
> Call this out β it's the same lesson the MCP Toolbox docs flag for bound params.
## Defense in depth below the tools (#6)
Even if a tool were subverted, the database role caps the blast radius. `toolbox_app`
holds `SELECT` on `products` and `SELECT/INSERT` on `orders` β and nothing more:
```
UPDATE products ... β permission denied
DELETE FROM orders β permission denied
DROP TABLE orders β must be owner of table
```
## Verifying it yourself
```bash
scripts/verify_security.sh
```
Runs 11 checks inside the stack (tokens minted via `keycloak:8080` so the issuer
matches what Toolbox validates) covering #2, #3, #5, and #6. Traces for every
call appear in Jaeger (#9).
## Production hardening (#7, #8, #10)
On GKE (`deploy/k8s/`): Cloud SQL via Workload Identity means **no DB password in
the cluster**; `tools.yaml` and secrets come from Secret Manager; a NetworkPolicy
ensures only `app=agent-web` can reach Toolbox and only Toolbox can reach the
databases. Swap the `authService` to `kind: google` for Google Sign-In β no other
change.
---
### Mcp Ai Agents Mcp Toolbox Security Agent Docs Architecture Diagram (`mcp_ai_agents/mcp_toolbox_security_agent/docs/architecture-diagram.md`)
# Technical architecture β MCP Toolbox as the security control plane
```
/* Detailed source-code truncated for AI context efficiency. */
```
## Legend
- **Green (bold)** β MCP Toolbox, the only component that touches data. The agent never holds a DB credential or runs raw SQL.
- **Red dashed** β the untrusted zone: the LLM and its tool arguments. Anything here is treated as hostile.
- **Solid thick arrows** β data-plane calls that Toolbox makes as a least-privilege role.
- **Dotted arrows** β identity/token flow (JWT issuance + OIDC validation).
- **#1β#10** β the ten security mechanisms (full map in [SECURITY.md](SECURITY.md)).
> Renders on GitHub, in [mermaid.live](https://mermaid.live), and VS Code's Mermaid preview.
---
--- METRICS ---
- Files Extracted: 6
- Estimated Token Budget: ~13100 tokens
- Canonical Reference: https://codewiki.google/github.com/Arindam200/awesome-ai-apps
