feat: add comprehensive documentation for AI Workspace, including architecture, memory model, profiles, services, and security guidelines

docs/mcp.md

@@ -0,0 +1,73 @@
+# MCP Integration
+
+The Model Context Protocol (MCP) is the workspace's standard interface for exposing local context to AI clients.
+
+## Role In AI Workspace
+
+`aiw-context-mcp` is a read-only context server. It exposes bounded profile context through MCP tools and resources.
+
+It should not:
+
+- capture communication traffic;
+- send messages;
+- write canonical memory;
+- promote facts automatically;
+- expose secrets or raw credentials.
+
+## MCP Concepts
+
+MCP uses a host/client/server model:
+
+- **Host**: the AI app, such as OpenCode, Claude Code, VS Code, Copilot, or another client.
+- **Client**: the connection the host opens to a server.
+- **Server**: a local or remote program that exposes context.
+
+Servers expose primitives such as:
+
+- **Tools**: callable functions.
+- **Resources**: readable context objects.
+- **Prompts**: reusable prompt templates.
+
+AI Workspace currently focuses on tools and resources.
+
+## Current Tools
+
+Examples:
+
+- `context_profiles`
+- `project_current_context`
+- `project_search_memory`
+- `memory_hybrid_search`
+- `communication_latest`
+- `communication_date_context`
+- `communication_standup_context`
+- `photos_latest`
+
+## Current Resources
+
+Examples:
+
+```text
+aiw://profiles/fidelity/current-work
+aiw://profiles/fidelity/work-items
+aiw://profiles/fidelity/mattermost/latest
+aiw://profiles/fidelity/photos/latest
+```
+
+## Security Posture
+
+MCP tools can be model-controlled in many clients, so this workspace defaults to read-only context tools. If write tools are added later, they should require clear user intent, narrow scope, and audit-friendly outputs.
+
+## Start The MCP Server
+
+HTTP transport:
+
+```bash
+python3 scripts/aiw/services.py start aiw-context-mcp --profile fidelity
+```
+
+stdio transport:
+
+```bash
+python3 scripts/mcp/aiw-context-mcp/server.py --transport stdio
+```