Ajustes na documentação e remanejamento dos folders

2026-07-09 14:04:19 +00:00 · 2026-06-21 10:25:02 -03:00
parent 8659eb552a
commit fe194a9f2a
10 changed files with 1430 additions and 22 deletions
--- a/docs/MCP_GATEWAY_DISCOVERY.md
+++ b/docs/MCP_GATEWAY_DISCOVERY.md
@@ -0,0 +1,156 @@
+# MCP Gateway — Server Discovery and Catalog Sync
+
+## Goal
+
+This evolution allows the MCP Gateway to discover tools from registered MCP Servers by reading a manifest or catalog endpoint.
+
+The framework still points to a single MCP Gateway:
+
+```env
+MCP_GATEWAY_ENABLED=true
+MCP_GATEWAY_URL=http://localhost:8300
+MCP_GATEWAY_TIMEOUT_SECONDS=60
+```
+
+The MCP Gateway can point to many MCP Servers:
+
+```text
+Agent Framework
+  -> MCP Gateway
+     -> telecom_mcp_server
+     -> retail_mcp_server
+     -> nf_items_mcp_server
+     -> any other MCP Server
+```
+
+## What is automatic
+
+After a server is registered in `apps/mcp_gateway/config/mcp_gateway.yaml` with `discover: true`, the gateway can:
+
+- call its manifest/catalog endpoint;
+- normalize the returned tool list;
+- publish the tools in `GET /v1/tools`;
+- execute the discovered tool through `POST /v1/tools/{tool_name}/invoke`.
+
+## What is still explicit
+
+The gateway does not scan the network or GitHub by itself. You still register the MCP Server endpoint in YAML.
+
+Example:
+
+```yaml
+servers:
+  nf_items:
+    enabled: true
+    discover: true
+    protocol: legacy_http
+    transport: http
+    url: http://localhost:8400/mcp
+    catalog_endpoint: /tools
+    invoke_endpoint: /tools/call
+    timeout_seconds: 30
+```
+
+If `catalog_endpoint` is omitted, the gateway tries:
+
+```text
+/.well-known/mcp-server.json
+/manifest
+/mcp/tools
+/tools/list
+/tools
+/v1/tools
+```
+
+## Expected manifest/catalog formats
+
+The gateway accepts common shapes:
+
+```json
+{
+  "server_id": "nf_items",
+  "tools": [
+    {
+      "name": "buscar_notas_por_criterios",
+      "description": "Search invoice items by criteria.",
+      "input_schema": {
+        "cliente": "string",
+        "estado": "string",
+        "preco": "number",
+        "ean": "string",
+        "margem": "number"
+      }
+    }
+  ]
+}
+```
+
+It also accepts:
+
+```json
+{"tools": [...]}
+```
+
+```json
+{"data": {"tools": [...]}}
+```
+
+```json
+{"capabilities": {"tools": [...]}}
+```
+
+## New endpoints
+
+### List discovery servers
+
+```bash
+curl http://localhost:8300/v1/discovery/servers | jq
+```
+
+### Force catalog sync
+
+```bash
+curl -X POST http://localhost:8300/v1/discovery/sync | jq
+```
+
+### List merged static + discovered tools
+
+```bash
+curl http://localhost:8300/v1/tools | jq
+```
+
+## Precedence rule
+
+Static tools configured under `tools:` override discovered tools with the same name. This allows operations teams to override timeout, cache, allowed agents, required business keys, and endpoint behavior safely.
+
+## Plugging a new MCP Server
+
+1. Start the MCP Server.
+2. Confirm that it exposes a catalog or manifest endpoint.
+3. Add it under `servers:` in `mcp_gateway.yaml` with `discover: true`.
+4. Restart the MCP Gateway or call `POST /v1/discovery/sync`.
+5. Confirm the tool appears in `GET /v1/tools`.
+6. Invoke the tool through the gateway.
+
+## Example invocation
+
+```bash
+curl -s -X POST http://localhost:8300/v1/tools/buscar_notas_por_criterios/invoke \
+  -H "Content-Type: application/json" \
+  -d '{
+    "tenant_id": "default",
+    "agent_id": "telecom_contas",
+    "channel": "web",
+    "tool_name": "buscar_notas_por_criterios",
+    "arguments": {
+      "cliente": "CLIENTE-001",
+      "estado": "SP",
+      "preco": 100.0,
+      "ean": "7890000000000",
+      "margem": 0.05
+    },
+    "business_context": {
+      "session_key": "session-001"
+    }
+  }' | jq
+```