┌─────────────────┐     ┌──────────────────────┐     ┌──────────────┐
│  Your Tools      │     │      ToolsDNS          │     │  AI Agent    │
│                  │     │                       │     │              │
│ • MCP Servers    │────▶│  Index + Embed        │     │ "What can    │
│ • Skill files    │     │  5,000+ tool schemas  │◀────│  you do?"    │
│ • Config files   │     │                       │     │              │
│ • Custom tools   │     │  list_skills()        │────▶│ (sees your   │
│ • OpenAPI specs  │     │  search_tools(query)  │     │  skills)     │
└─────────────────┘     │  → returns 1-3 tools  │────▶│              │
                         └──────────────────────┘     │ "Send email  │
                                                       │  to Alice"   │
                                                       └──────────────┘

curl -sSL https://raw.githubusercontent.com/syedfahimdev/ToolsDNS/master/deploy.sh | sudo bash

git clone https://github.com/syedfahimdev/ToolsDNS.git
cd ToolsDNS
pip install -e .
toolsdns serve

git clone https://github.com/syedfahimdev/ToolsDNS.git
cd ToolsDNS
cp .env.example .env          # set TOOLDNS_API_KEY
docker compose up -d

curl http://localhost:8787/health
# {"status":"healthy","tools_indexed":0,"sources":0}

tooldns system-prompt

curl https://api.toolsdns.com/v1/system-prompt \
  -H "Authorization: Bearer td_your_key"

## ToolsDNS — Tool Discovery Layer

You have access to 5,056 tools indexed in ToolsDNS...

### Available Skills
- **cea-weekly-report**: Fill the weekly Excel report...
- **everi-work-order**: Create Excel work orders for parts and returns...
...

{
  "mcpServers": {
    "tooldns": {
      "type": "streamable-http",
      "url": "https://api.yourdomain.com/mcp",
      "headers": { "Authorization": "Bearer td_your_key" }
    }
  }
}

User: "Create a work order for the maintenance team"

Agent → list_skills()                    # What skills exist?
      → sees "everi-work-order" listed
      → read_skill("everi-work-order")   # Get full instructions
      → follows SKILL.md instructions
      → creates the Excel work order ✓
      → work_order_get_file()            # Returns download URL, not base64
      → sends file to user ✓

curl -X POST http://localhost:8787/v1/sources \
  -H "Authorization: Bearer td_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "mcp_http",
    "name": "composio",
    "url": "https://mcp.composio.dev/composio/mcp?apiKey=YOUR_COMPOSIO_KEY"
  }'
# {"name":"composio","tools_count":2516,"status":"active"}

curl -X POST http://localhost:8787/v1/search \
  -H "Authorization: Bearer td_your_key" \
  -H "Content-Type: application/json" \
  -d '{"query": "send an email via gmail", "top_k": 1}'

{
  "results": [{
    "id": "composio__GMAIL_SEND_EMAIL",
    "name": "GMAIL_SEND_EMAIL",
    "description": "Sends an email via Gmail API using the authenticated user's Google profile",
    "confidence": 0.94,
    "match_reason": "strong semantic match (0.94); keyword match (BM25 0.87)",
    "input_schema": { "to": "string", "subject": "string", "body": "string" }
  }],
  "total_tools_indexed": 5056,
  "tokens_saved": 284710,
  "search_time_ms": 17.4
}

curl -X POST http://localhost:8787/v1/call \
  -H "Authorization: Bearer td_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "tool_id": "composio__GMAIL_SEND_EMAIL",
    "arguments": {
      "to": ["alice@example.com"],
      "subject": "Hello from ToolsDNS",
      "body": "This email was sent by an AI agent via ToolsDNS."
    }
  }'
# {"type":"mcp_result","result":{"status":"sent","messageId":"..."}}

import httpx

BASE = "http://localhost:8787"
HEADERS = {"Authorization": "Bearer td_your_key"}

client = httpx.Client(base_url=BASE, headers=HEADERS)

# 1. Search
results = client.post("/v1/search", json={"query": "create a GitHub issue", "top_k": 1}).json()
tool = results["results"][0]
print(f"Found: {tool['name']} (confidence: {tool['confidence']:.0%})")

# 2. Execute
result = client.post("/v1/call", json={
    "tool_id": tool["id"],
    "arguments": {
        "owner": "myorg",
        "repo": "myrepo",
        "title": "Bug: login fails on Safari",
        "body": "Steps to reproduce..."
    }
}).json()
print(result)

User: "Send a Slack message to #alerts that the deploy succeeded"

Agent → search_tools("send slack message")
      → gets: SLACK_SEND_MESSAGE (confidence 91%)
      → call_tool("composio__SLACK_SEND_MESSAGE", {
            "channel": "#alerts",
            "text": "✅ Deploy succeeded"
        })
      → "Message sent."

curl -X POST http://localhost:8787/v1/preflight \
  -H "Authorization: Bearer td_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Check my calendar for next week and send the summary to fahim via email",
    "top_k": 5,
    "include_schemas": true,
    "include_call_templates": true,
    "format": "context_block"
  }'

{
  "found": true,
  "tools": [
    {"tool_id": "composio__GOOGLECALENDAR_FIND_EVENT", "confidence": 0.88, "call_template": "..."},
    {"tool_id": "composio__GMAIL_SEND_EMAIL", "confidence": 0.81, "call_template": "..."}
  ],
  "queries_used": ["Check my calendar for next week", "send the summary...", "GOOGLECALENDAR_FIND_EVENT", "GMAIL_SEND_EMAIL"],
  "search_time_ms": 45.2
}

[ToolsDNS Auto-Discovery] — tools already found, DO NOT search again.

>>> CALL THIS NOW: toolsdns(action="call", tool_id="composio__GOOGLECALENDAR_FIND_EVENT", arguments={...})
    (tool: GOOGLECALENDAR_FIND_EVENT — Finds events in a Google Calendar)

>>> CALL THIS NOW: toolsdns(action="call", tool_id="composio__GMAIL_SEND_EMAIL", arguments={...})
    (tool: GMAIL_SEND_EMAIL — Sends an email via Gmail)

import httpx

# Call preflight BEFORE the LLM loop
resp = httpx.post("http://localhost:8787/v1/preflight", headers=HEADERS, json={
    "message": user_message,
    "format": "context_block",
    "include_schemas": True,
})
context = resp.json().get("context_block", "")

# Inject into system prompt or first user message
messages = [
    {"role": "system", "content": f"You are an AI assistant.\n\n{context}"},
    {"role": "user", "content": user_message},
]
# LLM now knows exactly which tools to call — no search step needed

curl -X POST http://localhost:8787/v1/search \
  -H "Authorization: Bearer td_your_key" \
  -d '{"query": "send email", "top_k": 2, "minimal": true}'

# Create a session
curl -X POST http://localhost:8787/v1/sessions \
  -H "Authorization: Bearer td_your_key" \
  -d '{"agent_id": "email-agent-1", "ttl_seconds": 3600}'
# → {"session_id": "sess_abc123", ...}

# Use session in searches
curl -X POST http://localhost:8787/v1/search \
  -H "Authorization: Bearer td_your_key" \
  -d '{
    "query": "send email",
    "session_id": "sess_abc123"
  }'

{
  "results": [{
    "id": "composio__GMAIL_SEND_EMAIL",
    "name": "GMAIL_SEND_EMAIL",
    "description": "[already seen — use cached schema] Sends an email...",
    "input_schema": {},
    "already_seen": true
  }],
  "tokens_saved_by_dedup": 150
}

curl -X POST http://localhost:8787/v1/search/batch \
  -H "Authorization: Bearer td_your_key" \
  -d '{
    "queries": [
      {"query": "send gmail email", "top_k": 1},
      {"query": "create github issue", "top_k": 1},
      {"query": "upload to google drive", "top_k": 1}
    ],
    "minimal": true,
    "session_id": "shared_session_abc"
  }'

# Create a profile for email agents
curl -X POST http://localhost:8787/v1/profiles \
  -H "Authorization: Bearer td_your_key" \
  -d '{
    "name": "email-agent",
    "description": "Agent for email and calendar tasks",
    "tool_patterns": ["GMAIL_*", "OUTLOOK_*", "GOOGLECALENDAR_*"],
    "pinned_tool_ids": ["composio__SLACK_SEND_MESSAGE"]
  }'

curl -X POST http://localhost:8787/v1/search \
  -H "Authorization: Bearer td_your_key" \
  -d '{
    "query": "send message",
    "profile": "email-agent"
  }'

curl http://localhost:8787/v1/cost-report \
  -H "Authorization: Bearer td_your_key"

{
  "lifetime": {
    "total_searches": 15234,
    "tokens_saved_by_search": 4321092,
    "tokens_saved_by_dedup": 892341,
    "total_tokens_saved": 5213433,
    "cost_saved_usd": 15.64,
    "model": "claude-sonnet-4-6"
  },
  "cache": {"hit_rate": 0.73},
  "active_sessions": 16,
  "active_profiles": ["email-agent", "code-agent", "data-agent"]
}

tooldns new-skill

~/.tooldns/skills/
└── my-workflow/
    ├── SKILL.md        ← required: frontmatter + agent instructions
    ├── tools.py        ← optional: Python tool functions called via bash
    └── template.xlsx   ← optional: any supporting files (xlsx, pdf, etc.)

---
name: my-workflow
description: "One sentence — what this skill does and when to use it"
user-invocable: true
---

# My Workflow

Step-by-step instructions for the agent...

tooldns ingest
# or for a specific skill only:
python3 -m tooldns.cli ingest --skill my-workflow

curl https://api.toolsdns.com/v1/system-prompt \
  -H "Authorization: Bearer td_your_key"

curl -X POST https://api.toolsdns.com/v1/search \
  -H "Authorization: Bearer td_your_key" \
  -H "Content-Type: application/json" \
  -d '{"query": "create a github issue", "top_k": 3}'

{
  "results": [{
    "name": "GITHUB_CREATE_ISSUE",
    "description": "Creates a new issue in a GitHub repository",
    "confidence": 0.94,
    "match_reason": "strong semantic match (0.94); keyword match (BM25 0.87)",
    "category": "Dev & Code",
    "how_to_call": {
      "type": "mcp",
      "server": "composio",
      "instruction": "Call this tool via the 'composio' MCP server."
    }
  }],
  "total_tools_indexed": 5056,
  "tokens_saved": 284710,
  "search_time_ms": 17.4
}

curl "https://api.toolsdns.com/v1/tools?category=Dev%20%26%20Code&limit=50" \
  -H "Authorization: Bearer td_your_key"

curl https://api.toolsdns.com/v1/skills \
  -H "Authorization: Bearer td_your_key"

curl https://api.toolsdns.com/dl/{token} --output report.xlsx

curl https://api.toolsdns.com/health
# {"status":"healthy","tools_indexed":5056,"sources":4}

curl -X POST https://api.toolsdns.com/v1/search/batch \
  -H "Authorization: Bearer td_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "queries": [
      {"query": "send email", "top_k": 1},
      {"query": "create github issue", "top_k": 1}
    ],
    "minimal": true,
    "session_id": "sess_abc123"
  }'

curl -X POST https://api.toolsdns.com/v1/sessions \
  -H "Authorization: Bearer td_your_key" \
  -d '{"agent_id": "email-agent-1", "ttl_seconds": 3600}'
# → {"session_id": "sess_abc123", "expires_at": "..."}

curl -X POST https://api.toolsdns.com/v1/profiles \
  -H "Authorization: Bearer td_your_key" \
  -d '{
    "name": "email-agent",
    "tool_patterns": ["GMAIL_*", "OUTLOOK_*"]
  }'

curl https://api.toolsdns.com/v1/cost-report \
  -H "Authorization: Bearer td_your_key"

curl -sSL https://raw.githubusercontent.com/syedfahimdev/ToolsDNS/master/deploy.sh | sudo bash

# /etc/caddy/Caddyfile
api.yourdomain.com {
    reverse_proxy localhost:8787
}

TOOLDNS_API_KEY=td_your_strong_key
TOOLDNS_PUBLIC_URL=https://your-app.railway.app

ToolsDNS/
├── deploy.sh              # One-command VPS installer (creates both systemd services)
├── tooldns.sh             # Management CLI (status, ingest, mcp-status, update)
├── main.py                # FastAPI app + network ACL + /dl/{token} download endpoint
├── Dockerfile             # Container image — pre-bakes embedding model
├── docker-compose.yml     # Two services: REST API (8787) + MCP server (8788)
├── .env.example           # All supported env vars with descriptions
├── pyproject.toml         # Package config — CLI: toolsdns / tooldns
├── tooldns/               # Main Python package
│   ├── api.py             # REST API routes (/v1/*)
│   ├── auth.py            # API key auth — admin key + named sub-keys
│   ├── categories.py      # Auto-categorization (15 categories)
│   ├── cli.py             # CLI: toolsdns setup / serve / system-prompt / ...
│   ├── config.py          # Settings from env vars
│   ├── database.py        # SQLite with FTS5 full-text + embedding cache
│   ├── discover.py        # Auto-discover from Smithery/npm/GitHub/HTTP
│   ├── embedder.py        # Local embeddings (BGE/ONNX/sentence-transformers/Ollama)
│   ├── fetcher.py         # MCP protocol client (stdio + HTTP transport)
│   ├── health.py          # Source health monitor + webhook alerts
│   ├── ingestion.py       # Parallel tool indexing pipeline
│   ├── marketplace.py     # Pre-built MCP server catalog
│   ├── mcp_server.py      # FastMCP server — persistent HTTP on port 8788
│   ├── models.py          # Pydantic models
│   ├── search.py          # Hybrid semantic + BM25 + LRU query cache
│   └── tokens.py          # Real token counting + per-model cost calc
└── .github/
    ├── workflows/ci.yml           # Tests, import checks, branding lint
    └── workflows/security.yml     # Bandit, Safety CVE scan, secret detection

# 1. Fork the repo on GitHub, then clone your fork
git clone https://github.com/YOUR_USERNAME/ToolsDNS.git
cd ToolsDNS

# 2. Create a virtual environment
python3 -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate

# 3. Install in editable mode
pip install -e .

# 4. Create a branch off develop for your feature
git checkout develop
git checkout -b feat/my-new-feature

# 5. Make changes, then test
toolsdns serve
curl http://localhost:8787/health  # verify it's running

# 6. Push and open a PR against develop
git push origin feat/my-new-feature

{
    "id": "notion",
    "name": "Notion",
    "description": "Read and write Notion pages, databases, and blocks",
    "category": "Productivity",
    "emoji": "📝",
    "install": {
        "type": "mcp_http",
        "url": "https://mcp.notion.com/v1",
        "env_vars": ["NOTION_API_KEY"],
    }
}

---
name: your-skill-name
description: What this skill does in one sentence
---

# Your Skill Name

Step-by-step instructions for the agent to follow...