dedsecorg · dedsecorg · Aug 29, 2026 · Aug 29, 2026 · Aug 29, 2026 · Aug 29, 2026
@@ -1,15 +1,41 @@
 # agentic-dns
 
-[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
-[![CI Status](https://github.com/dedsecorg/agentic-dns/workflows/CI/badge.svg)](https://github.com/dedsecorg/agentic-dns/actions)
-[![Protocol: MCP](https://img.shields.io/badge/MCP-JSON--RPC-success.svg)](docs/MCP_GUIDE.md)
-[![Docker: GHCR](https://img.shields.io/badge/Docker-GHCR-blue.svg)](https://github.com/dedsecorg/agentic-dns/pkgs/container/agentic-dns)
-[![GitHub Stars](https://img.shields.io/github/stars/dedsecorg/agentic-dns?style=flat&color=yellow)](https://github.com/dedsecorg/agentic-dns/stargazers)
-[![Release](https://img.shields.io/badge/Release-v1.5.0-blue)](https://github.com/dedsecorg/agentic-dns/releases)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE) [![CI Status](https://github.com/dedsecorg/agentic-dns/workflows/CI/badge.svg)](https://github.com/dedsecorg/agentic-dns/actions) [![Protocol: MCP](https://img.shields.io/badge/MCP-JSON--RPC-success.svg)](docs/MCP_GUIDE.md) [![Docker: GHCR](https://img.shields.io/badge/Docker-GHCR-blue.svg)](https://github.com/dedsecorg/agentic-dns/pkgs/container/agentic-dns) [![GitHub Stars](https://img.shields.io/github/stars/dedsecorg/agentic-dns?style=flat&color=yellow)](https://github.com/dedsecorg/agentic-dns/stargazers) [![Release](https://img.shields.io/badge/Release-v1.5.0-blue)](https://github.com/dedsecorg/agentic-dns/releases)
 
-> POSIX-Native DNS Routing, Diagnostic, and Telemetry Engine for Agentic AI Systems (Claude, Cursor, Windsurf, Hermes Agent, Copilot).
+Local agentic DNS stack combining Pi-hole, CoreDNS, dnsdist, and Unbound with an MCP-compatible stdio server for programmatic control.
 
-`agentic-dns` is a zero-dependency, ultra-fast DNS orchestration engine written in pure Bash and Rust. Designed for developer workstations, homelabs, Kubernetes nodes, and autonomous AI agents, it manages multi-tier DNS chains (`pihole` -> `coredns` -> `dnsdist` -> `unbound` -> `dnscrypt` -> `VPN DNS`), executes live hop-by-hop packet traces (`trace`), auto-bypasses failing upstreams (`bypass`), and exposes a stdio Model Context Protocol (MCP JSON-RPC) server for AI coding assistants.
+---
+
+## Machine-friendly summary
+
+```
+Name: agentic-dns
+URL: https://github.com/dedsecorg/agentic-dns
+ShortDescription: Local agentic DNS stack combining Pi-hole, CoreDNS, dnsdist, and Unbound with an MCP-compatible stdio server for programmatic control.
+Keywords: agentic-dns, mcp, dns, pi-hole, coredns, dnsdist, unbound, selfhosted, dns-middleware
+EntryPoint: bin/agentic-dns
+Install:
+  - git clone https://github.com/dedsecorg/agentic-dns.git
+  - ./install.sh
+CLIExamples:
+  - MCP: agentic-dns mcp
+  - API: agentic-dns api
+MCP:
+  - protocol: stdio
+  - capabilities: dns_status,dns_query,dns_trace,dns_health,dns_routes,dns_pihole_log,dns_bypass
+  - control-endpoint: stdio
+  - example-config-snippet: |
+      mcp:
+        name: agentic-dns
+        protocol: stdio
+        command: ["agentic-dns","mcp"]
+Maintainer:
+  - name: dedsecorg
+  - contact: https://github.com/dedsecorg
+License: MIT
+ReleaseTag: v1.5.0
+Notes: Exposes MCP features for query/response and local firewall integration. See README.md for full architecture and network requirements.
+```
 
 ---
 
@@ -87,6 +113,26 @@ Once connected, ask your AI coding assistant:
 
 ---
 
+## MCP configuration
+
+```yaml
+mcp:
+  name: agentic-dns
+  protocol: stdio
+  command: ["agentic-dns","mcp"]
+  capabilities:
+    - dns_status
+    - dns_query
+    - dns_trace
+    - dns_health
+    - dns_routes
+    - dns_pihole_log
+    - dns_bypass
+  version: 1.0
+```
+
+---
+
 ## 6-Tier Architecture Pipeline
 
 ```
@@ -104,17 +150,23 @@ Once connected, ask your AI coding assistant:
    +--------+--------+
    |                 |
    v                 v
-unbound (:5335)   dnscrypt-proxy (:5354) / stubby (:5360)
+ unbound (:5335)   dnscrypt-proxy (:5354) / stubby (:5360)
    |                 |
    v                 v
-[VPN / Upstream]  [DoH / DoT Cloud Upstreams]
+ [VPN / Upstream]  [DoH / DoT Cloud Upstreams]
 ```
 
 ---
 
 ## CLI Command Quick Reference
 
 ```bash
+# Start stdio MCP JSON-RPC Server
+agentic-dns mcp
+
+# Start REST API server on port 8099
+agentic-dns api
+
 # View active DNS chain status and listening ports
 agentic-dns status
 
@@ -130,15 +182,18 @@ agentic-dns health
 # View Pi-hole query logs
 agentic-dns pihole-log
 
-# Start REST API server on port 8099
-agentic-dns api
-
-# Start stdio MCP JSON-RPC Server
-agentic-dns mcp
+# Start the Rust API/DoT proxy server (if built)
+agentic-dns server
 ```
 
 ---
 
+## Tags / Keywords
+
+agentic-dns, mcp, dns, pi-hole, coredns, dnsdist, unbound, selfhosted
+
+---
+
 ## License
 
 [MIT License](LICENSE) - Free and Open Source.
@@ -1,66 +1,47 @@
-# agentic-dns - LLM Knowledge Base & Integration Reference
+# agentic-dns
 
-> POSIX-Native DNS Routing, Diagnostic, and Telemetry Engine for Agentic AI Systems.
+Local agentic DNS stack combining Pi-hole, CoreDNS, dnsdist, and Unbound with an MCP-compatible stdio server for programmatic control.
 
-## Project Overview
+## Machine-friendly summary
 
-`agentic-dns` is a zero-dependency, ultra-fast DNS orchestration engine written in pure Bash and Rust. It manages multi-tier DNS chains (`pihole` -> `coredns` -> `dnsdist` -> `unbound` -> `dnscrypt` -> `VPN DNS`), executes live hop-by-hop packet traces (`trace`), auto-bypasses failing upstreams (`bypass`), and exposes a stdio Model Context Protocol (MCP JSON-RPC) server for AI coding assistants.
+Name: agentic-dns
 
----
+ShortDescription: Local agentic DNS stack combining Pi-hole, CoreDNS, dnsdist, and Unbound with an MCP-compatible stdio server for programmatic control.
 
-## 1-Line Installation
+Keywords: agentic-dns, mcp, dns, pi-hole, coredns, dnsdist, unbound, selfhosted, dns-middleware
 
-```bash
-curl -fsSL https://raw.githubusercontent.com/dedsecorg/agentic-dns/main/install.sh | bash
-```
-
----
+EntryPoint: bin/agentic-dns
 
-## CLI Usage Reference
+Install:
+- git clone https://github.com/dedsecorg/agentic-dns.git
+- ./install.sh
 
-- `agentic-dns status`: Show live service status, IP addresses, listening ports, and active DNS chain.
-- `agentic-dns query <domain>`: Resolve domain through the primary DNS entrypoint.
-- `agentic-dns trace <domain>`: Execute live simultaneous background packet captures across loopback and network interfaces to visualize packet hop progression.
-- `agentic-dns routes`: List active routing rules from `dnsdist` configuration.
-- `agentic-dns route add <name> <addr:port>`: Add upstream resolver server to `dnsdist`.
-- `agentic-dns route remove <name>`: Remove upstream server from `dnsdist`.
-- `agentic-dns bypass <failing_service> [backup_service]`: Dynamically bypass a failing DNS resolver and reroute traffic to a healthy backup.
-- `agentic-dns enforce <on|off|status|clean> [target_ip]`: Apply non-destructive `nftables` rules to intercept Private DNS (DoT port 853) and drop Google DoQ (UDP/443).
-- `agentic-dns pihole-log`: Query recent DNS queries and top clients from Pi-hole SQLite database (`/etc/pihole/pihole-FTL.db`).
-- `agentic-dns health`: Execute health check sweeps across all registered DNS listeners.
-- `agentic-dns tag`: Show service classification tags (listening, entry-point, upstream, fallback).
-- `agentic-dns api`: Start local REST HTTP API server on port 8099.
-- `agentic-dns mcp`: Start stdio MCP JSON-RPC protocol server for AI agents.
+CLI Examples:
+- MCP server (stdio JSON-RPC): `agentic-dns mcp`
+- REST API server: `agentic-dns api`
 
----
+## MCP Configuration (example)
 
-## Model Context Protocol (MCP) JSON-RPC Tools
+```yaml
+mcp:
+  name: agentic-dns
+  protocol: stdio
+  command: ["agentic-dns","mcp"]
+  capabilities:
+    - dns_status
+    - dns_query
+    - dns_trace
+    - dns_health
+    - dns_routes
+    - dns_pihole_log
+    - dns_bypass
+  version: 1.0
+```
 
-Exposed MCP Tools:
-- `dns_status`: Retrieve status of all services and active chain.
-- `dns_query`: Resolve domain through the pipeline.
-- `dns_trace`: Spawns live packet capture trace across inter-service hops.
-- `dns_health`: Runs health check sweep across listeners.
-- `dns_routes`: Lists current dnsdist backend rules.
-- `dns_pihole_log`: Queries SQLite query log.
-- `dns_bypass`: Auto-switches routing around failing upstreams.
+## Maintainer
 
----
+- dedsecorg — https://github.com/dedsecorg
 
-## AI Agent Integration Configuration
+## License
 
-Add to `.mcp.json`:
-```json
-{
-  "mcpServers": {
-    "agentic-dns": {
-      "command": "agentic-dns",
-      "args": ["mcp"],
-      "env": {
-        "PIHOLE_HOST": "127.0.0.1",
-        "AGENTIC_DNS_API_PORT": "8099"
-      }
-    }
-  }
-}
-```
+MIT
@@ -1,66 +1,26 @@
-# agentic-dns - LLM Knowledge Base & Integration Reference
-
-> POSIX-Native DNS Routing, Diagnostic, and Telemetry Engine for Agentic AI Systems.
-
-## Project Overview
-
-`agentic-dns` is a zero-dependency, ultra-fast DNS orchestration engine written in pure Bash and Rust. It manages multi-tier DNS chains (`pihole` -> `coredns` -> `dnsdist` -> `unbound` -> `dnscrypt` -> `VPN DNS`), executes live hop-by-hop packet traces (`trace`), auto-bypasses failing upstreams (`bypass`), and exposes a stdio Model Context Protocol (MCP JSON-RPC) server for AI coding assistants.
-
----
-
-## 1-Line Installation
-
-```bash
-curl -fsSL https://raw.githubusercontent.com/dedsecorg/agentic-dns/main/install.sh | bash
-```
-
----
-
-## CLI Usage Reference
-
-- `agentic-dns status`: Show live service status, IP addresses, listening ports, and active DNS chain.
-- `agentic-dns query <domain>`: Resolve domain through the primary DNS entrypoint.
-- `agentic-dns trace <domain>`: Execute live simultaneous background packet captures across loopback and network interfaces to visualize packet hop progression.
-- `agentic-dns routes`: List active routing rules from `dnsdist` configuration.
-- `agentic-dns route add <name> <addr:port>`: Add upstream resolver server to `dnsdist`.
-- `agentic-dns route remove <name>`: Remove upstream server from `dnsdist`.
-- `agentic-dns bypass <failing_service> [backup_service]`: Dynamically bypass a failing DNS resolver and reroute traffic to a healthy backup.
-- `agentic-dns enforce <on|off|status|clean> [target_ip]`: Apply non-destructive `nftables` rules to intercept Private DNS (DoT port 853) and drop Google DoQ (UDP/443).
-- `agentic-dns pihole-log`: Query recent DNS queries and top clients from Pi-hole SQLite database (`/etc/pihole/pihole-FTL.db`).
-- `agentic-dns health`: Execute health check sweeps across all registered DNS listeners.
-- `agentic-dns tag`: Show service classification tags (listening, entry-point, upstream, fallback).
-- `agentic-dns api`: Start local REST HTTP API server on port 8099.
-- `agentic-dns mcp`: Start stdio MCP JSON-RPC protocol server for AI agents.
-
----
-
-## Model Context Protocol (MCP) JSON-RPC Tools
-
-Exposed MCP Tools:
-- `dns_status`: Retrieve status of all services and active chain.
-- `dns_query`: Resolve domain through the pipeline.
-- `dns_trace`: Spawns live packet capture trace across inter-service hops.
-- `dns_health`: Runs health check sweep across listeners.
-- `dns_routes`: Lists current dnsdist backend rules.
-- `dns_pihole_log`: Queries SQLite query log.
-- `dns_bypass`: Auto-switches routing around failing upstreams.
-
----
-
-## AI Agent Integration Configuration
-
-Add to `.mcp.json`:
-```json
-{
-  "mcpServers": {
-    "agentic-dns": {
-      "command": "agentic-dns",
-      "args": ["mcp"],
-      "env": {
-        "PIHOLE_HOST": "127.0.0.1",
-        "AGENTIC_DNS_API_PORT": "8099"
-      }
-    }
-  }
-}
-```
+Name: agentic-dns
+URL: https://github.com/dedsecorg/agentic-dns
+ShortDescription: Local agentic DNS stack combining Pi-hole, CoreDNS, dnsdist, and Unbound with an MCP-compatible stdio server for programmatic control.
+Keywords: agentic-dns, mcp, dns, pi-hole, coredns, dnsdist, unbound, selfhosted, dns-middleware
+EntryPoint: bin/agentic-dns
+Install:
+  - git clone https://github.com/dedsecorg/agentic-dns.git
+  - ./install.sh
+CLIExamples:
+  - MCP: agentic-dns mcp
+  - API: agentic-dns api
+MCP:
+  - protocol: stdio
+  - capabilities: dns_status,dns_query,dns_trace,dns_health,dns_routes,dns_pihole_log,dns_bypass
+  - control-endpoint: stdio
+  - example-config-snippet: |
+      mcp:
+        name: agentic-dns
+        protocol: stdio
+        command: ["agentic-dns","mcp"]
+Maintainer:
+  - name: dedsecorg
+  - contact: https://github.com/dedsecorg
+License: MIT
+ReleaseTag: v1.5.0
+Notes: Exposes MCP features for query/response and local firewall integration. See README.md for full architecture and network requirements.
@@ -0,0 +1,3 @@
+REMOVED: pr_body.md was a temporary PR artifact and should not be kept in the repository.
+
+This file was committed during the pull-request process but contains transient notes for the PR author. Please remove this file from the branch before merging or ignore it; it has been replaced with machine-friendly metadata files (llms.txt, llms.md) and README updates.
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,3 @@
		REMOVED: pr_body.md was a temporary PR artifact and should not be kept in the repository.

		This file was committed during the pull-request process but contains transient notes for the PR author. Please remove this file from the branch before merging or ignore it; it has been replaced with machine-friendly metadata files (llms.txt, llms.md) and README updates.