docs+examples: working block-first quickstart, mock upstream, enforcing example policies

docker-compose.yml

@@ -1,47 +1,28 @@
+# Runs the cMCP gateway against the examples/minimal bundle, with a mock
+# upstream so an allowed tool call forwards end to end.
+#
+# The mock shares the gateway's network namespace (network_mode: service:gateway),
+# so the catalog's http://localhost:9001/mcp upstream resolves to the mock without
+# a separate hostname. Bring it up with:  docker compose up --build
 services:
   gateway:
     build: .
+    working_dir: /etc/cmcp
     ports:
       - "8443:8443"
     environment:
       CMCP_DEV_MODE: "1"
     volumes:
-      - ./examples/config.yaml:/etc/cmcp/config.yaml:ro
-      - ./examples/policy:/etc/cmcp/policy:ro
-      - ./examples/catalog.json:/etc/cmcp/catalog.json:ro
-    depends_on:
-      - mock-mcp-server
+      - ./examples/minimal/cmcp-config.yaml:/etc/cmcp/cmcp-config.yaml:ro
+      - ./examples/minimal/policies:/etc/cmcp/policies:ro
+      - ./examples/minimal/catalog.json:/etc/cmcp/catalog.json:ro
+    command: ["cmcp", "start", "--config", "/etc/cmcp/cmcp-config.yaml"]
 
   mock-mcp-server:
     image: python:3.11-slim
-    ports:
-      - "8080:8080"
-    command: >
-      python -c "
-      import http.server, json, sys
-
-      class Handler(http.server.BaseHTTPRequestHandler):
-          def log_message(self, format, *args):
-              pass
-          def do_POST(self):
-              length = int(self.headers.get('Content-Length', 0))
-              body = self.rfile.read(length)
-              try:
-                  msg = json.loads(body)
-              except Exception:
-                  msg = {}
-              response = json.dumps({
-                  'jsonrpc': '2.0',
-                  'id': msg.get('id'),
-                  'result': {'content': [{'type': 'text', 'text': 'mock response'}]}
-              }).encode()
-              self.send_response(200)
-              self.send_header('Content-Type', 'application/json')
-              self.send_header('Content-Length', str(len(response)))
-              self.end_headers()
-              self.wfile.write(response)
-
-      server = http.server.HTTPServer(('0.0.0.0', 8080), Handler)
-      print('mock-mcp-server listening on :8080', flush=True)
-      server.serve_forever()
-      "
+    network_mode: "service:gateway"
+    volumes:
+      - ./scripts/mock_upstream.py:/mock_upstream.py:ro
+    command: ["python", "/mock_upstream.py", "--port", "9001"]
+    depends_on:
+      - gateway