Lots of cleanups

Author: rjordan

AI_DEVELOPMENT_NOTES.md

@@ -1,62 +1,61 @@
-# Aetheria MCP Server - HTTP Streaming Transport
+# Aetheria MCP Server - HTTP Access Guide
 
-The Aetheria MCP (Model Context Protocol) server now uses HTTP streaming transport instead of stdio, making it easier to integrate with web applications and HTTP clients.
+The Aetheria MCP (Model Context Protocol) server serves static world reference documentation as markdown files. It supports both stdio and HTTP transports.
 
 ## Starting the Server
 
+### Development Mode (stdio transport)
 ```bash
-cd site
-npm run mcp
+cd mcp-server
+npm run dev
 ```
 
-The server will start on port 3001 and bind to all network interfaces (0.0.0.0) by default. You can customize the configuration with environment variables:
+### HTTP Mode (for web integration)
+```bash
+cd mcp-server
+npm run build
+npm run start-http
+```
+
+The HTTP server will start on port 3000 and bind to all network interfaces (0.0.0.0) by default. You can customize with environment variables:
 
 ```bash
 # Change port
-MCP_PORT=8080 npm run mcp
+MCP_PORT=8080 npm run start-http
 
 # Bind to specific interface (localhost only)
-MCP_HOST=127.0.0.1 npm run mcp
-
-# Bind to all interfaces (default)
-MCP_HOST=0.0.0.0 npm run mcp
+MCP_HOST=127.0.0.1 npm run start-http
 
 # Custom port and host
-MCP_HOST=192.168.1.100 MCP_PORT=8080 npm run mcp
+MCP_HOST=192.168.1.100 MCP_PORT=8080 npm run start-http
 ```
 
 ## Network Access
 
-By default, the server binds to `0.0.0.0:3001`, making it accessible from:
-- **Local machine**: `http://localhost:3001`
-- **Local network**: `http://[your-ip]:3001`
-- **Docker/containers**: `http://0.0.0.0:3001`
-
-If you want to restrict access to localhost only, set `MCP_HOST=127.0.0.1`.
+By default, the HTTP server binds to `0.0.0.0:3000`, making it accessible from:
+- **Local machine**: `http://localhost:3000`
+- **Local network**: `http://[your-ip]:3000`
+- **Docker/containers**: `http://0.0.0.0:3000`
 
 ## Endpoints
 
 ### SSE (Server-Sent Events) Endpoint
-- **URL**: `http://localhost:3001`
+- **URL**: `http://localhost:3000`
 - **Method**: GET
 - **Headers**: `Accept: text/event-stream`
-- **Use case**: For persistent connections and real-time streaming
 
 ### JSON-RPC Endpoint
-- **URL**: `http://localhost:3001`
+- **URL**: `http://localhost:3000`
 - **Method**: POST
-- **Headers**:
-  - `Content-Type: application/json`
-  - `Accept: application/json, text/event-stream`
+- **Headers**: `Content-Type: application/json`
 
 ## Example Usage
 
 ### 1. Initialize the MCP Server
 
 ```bash
-curl -X POST http://localhost:3001 \
+curl -X POST http://localhost:3000 \
   -H "Content-Type: application/json" \
-  -H "Accept: application/json, text/event-stream" \
   -d '{
     "jsonrpc": "2.0",
     "id": 1,
@@ -65,7 +64,7 @@ curl -X POST http://localhost:3001 \
       "protocolVersion": "2024-11-05",
       "capabilities": {},
       "clientInfo": {
-        "name": "your-client",
+        "name": "aetheria-client",
         "version": "1.0.0"
       }
     }
@@ -75,9 +74,8 @@ curl -X POST http://localhost:3001 \
 ### 2. List Available Resources
 
 ```bash
-curl -X POST http://localhost:3001 \
+curl -X POST http://localhost:3000 \
   -H "Content-Type: application/json" \
-  -H "Accept: application/json, text/event-stream" \
   -d '{
     "jsonrpc": "2.0",
     "id": 2,
@@ -89,70 +87,100 @@ curl -X POST http://localhost:3001 \
 ### 3. Read a Resource
 
 ```bash
-curl -X POST http://localhost:3001 \
+curl -X POST http://localhost:3000 \
   -H "Content-Type: application/json" \
-  -H "Accept: application/json, text/event-stream" \
   -d '{
     "jsonrpc": "2.0",
     "id": 3,
     "method": "resources/read",
     "params": {
-      "uri": "aetheria://pages/magic"
+      "uri": "aetheria://page",
+      "arguments": {
+        "page": "magic"
+      }
     }
   }'
 ```
 
-### 4. Use Search Tool
+### 4. List Available Tools
 
 ```bash
-curl -X POST http://localhost:3001 \
+curl -X POST http://localhost:3000 \
   -H "Content-Type: application/json" \
-  -H "Accept: application/json, text/event-stream" \
   -d '{
     "jsonrpc": "2.0",
     "id": 4,
+    "method": "tools/list",
+    "params": {}
+  }'
+```
+
+### 5. Use Search Tool
+
+```bash
+curl -X POST http://localhost:3000 \
+  -H "Content-Type: application/json" \
+  -d '{
+    "jsonrpc": "2.0",
+    "id": 5,
     "method": "tools/call",
     "params": {
-      "name": "search_aetheria_pages",
+      "name": "search_pages",
       "arguments": {
-        "query": "magic schools"
+        "query": "magic schools",
+        "maxResults": 10
       }
     }
   }'
 ```
 
 ## Features
 
-- **Session Management**: Each connection gets a unique session ID for state management
-- **CORS Enabled**: The server allows cross-origin requests for web integration
-- **SSE Streaming**: Real-time event streaming for persistent connections
-- **JSON-RPC**: Standard JSON-RPC 2.0 protocol for request/response
-- **Puppeteer Integration**: Renders live page content from the Aetheria website
-- **Dynamic Resources**: Access to all Aetheria pages (magic, classes, equipment, etc.)
-- **Search Capability**: Search across all rendered page content
+- **Static File Serving**: Fast, reliable markdown file serving
+- **Session Management**: UUID-based session tracking
+- **CORS Enabled**: Cross-origin requests supported
+- **Dual Transport**: Both stdio and HTTP transport options
+- **Documentation Generation**: Serves pre-generated markdown docs
+- **Search Capability**: Full-text search across all content
 
 ## Available Resources
 
-The server provides access to the following Aetheria pages:
-- `aetheria://pages/magic` - Magic system information
-- `aetheria://pages/classes` - Character classes
-- `aetheria://pages/equipment` - Equipment and items
-- `aetheria://pages/politics` - Political systems
-- `aetheria://pages/alignment` - Alignment system
-- `aetheria://pages/religion` - Religious information
-- `aetheria://pages/relationships` - Character relationships
+The server provides a single resource endpoint:
+- `aetheria://page` - Get any page from the Aetheria world reference
+
+Available pages include:
+- `alignment` - Character alignment system
+- `classes` - Character classes and specializations
+- `equipment` - Weapons, armor, and items
+- `magic` - Magic schools and spells
+- `politics` - Political systems and organizations
+- `religion` - Deities and religious systems
+- `relationships` - Character relationships
+- `skills` - Skills and abilities
+- `index` - Main overview page
 
 ## Available Tools
 
-- `search_aetheria_pages` - Search across all Aetheria content for specific terms
+- `search_pages` - Search across all Aetheria documentation
+- `get_page_hierarchy` - Get structured page hierarchy
+- `generate_character_sheet` - Generate character sheets (if available)
+- `extract_entities` - Extract specific entity types
 
 ## Technical Details
 
-- **Transport**: HTTP Streaming (SSE + JSON-RPC)
+- **Architecture**: Simple file-based serving (no browser automation)
 - **Protocol**: Model Context Protocol (MCP) 2024-11-05
-- **Session**: UUID-based session management
-- **Rendering**: Puppeteer for dynamic content extraction
-- **CORS**: Enabled for cross-origin access
-- **Port**: 3001 (configurable via MCP_PORT)
+- **Transport**: HTTP Streaming + stdio options
+- **Performance**: Fast static file serving
+- **Dependencies**: Minimal (no Puppeteer, no heavy frameworks)
+- **Data Source**: Pre-generated markdown files in `/docs` directory
+- **Port**: 3000 (configurable via MCP_PORT)
+
+## Development Workflow
+
+1. **Generate docs**: Content is generated from the SolidJS site
+2. **Build server**: `npm run build` compiles TypeScript
+3. **Start server**: `npm run start-http` for HTTP access
+4. **Test**: Use curl commands above to verify functionality
 
-The server automatically handles session initialization, cleanup, and provides both streaming and request/response modes depending on the client needs.
+The server is lightweight, fast, and reliable - perfect for AI model integration without the complexity of browser automation.