docs: document and configure MCP tool integration

- Create comprehensive MCP.md documenting all available tools:
  * Hugging Face Hub (models, datasets, papers, spaces, docs)
  * Web search and fetch for research
  * Code tools (Bash, Git, file ops)
  * Claude Code (GSD) workflow agents

- Map MCP usage to specific phases:
  * Phase 1: Model discovery (Mistral, Llama, quantized options)
  * Phase 2: Safety research (sandboxing, verification papers)
  * Phase 5: Conversation datasets and papers
  * Phase 12: Voice visualization models and spaces
  * Phase 13: Avatar generation tools and research
  * Phase 14: Mobile inference frameworks and patterns

- Update config.json with MCP settings:
  * Enable Hugging Face (mystiatech authenticated)
  * Enable WebSearch for current practices
  * Set default result limits

- Update PROJECT.md constraints to document MCP enablement

Research phases will leverage MCPs extensively for optimal
library/model selection, architecture patterns, and best practices.

.planning/MCP.md

@@ -0,0 +1,220 @@
+# Available Tools & MCP Integration
+
+This document lists all available tools and MCP (Model Context Protocol) servers that Mai development can leverage.
+
+## Hugging Face Hub Integration
+
+**Status**: Authenticated as `mystiatech`
+
+### Tools Available
+
+#### Model Discovery
+- `mcp__claude_ai_Hugging_Face__model_search` — Search ML models by task, author, library, trending
+- `mcp__claude_ai_Hugging_Face__hub_repo_details` — Get detailed info on any model, dataset, or space
+
+**Use Cases:**
+- Phase 1: Discover quantized models for local inference (Mistral, Llama, etc.)
+- Phase 12: Find audio/voice models for visualization
+- Phase 13: Find avatar/animation models (VRoid compatible options)
+- Phase 14: Research Android-compatible model formats
+
+#### Dataset Discovery
+- `mcp__claude_ai_Hugging_Face__dataset_search` — Find datasets by task, author, tags, trending
+- Search filters: language, size, task categories
+
+**Use Cases:**
+- Phase 4: Training data research for memory compression
+- Phase 5: Conversation quality datasets
+- Phase 12: Audio visualization datasets
+
+#### Research Papers
+- `mcp__claude_ai_Hugging_Face__paper_search` — Search ML research papers with abstracts
+
+**Use Cases:**
+- Phase 2: Safety and sandboxing research papers
+- Phase 4: Memory system and RAG papers
+- Phase 5: Conversational AI and reasoning papers
+- Phase 7: Self-improvement and code generation papers
+
+#### Spaces & Interactive Models
+- `mcp__claude_ai_Hugging_Face__space_search` — Discover Hugging Face Spaces (demos)
+- `mcp__claude_ai_Hugging_Face__dynamic_space` — Run interactive tasks (Image Gen, OCR, TTS, etc.)
+
+**Use Cases:**
+- Phase 12: Voice/audio visualization demos
+- Phase 13: Avatar generation or manipulation
+- Phase 14: Android UI pattern research
+
+#### Documentation
+- `mcp__claude_ai_Hugging_Face__hf_doc_search` — Search HF docs and guides
+- `mcp__claude_ai_Hugging_Face__hf_doc_fetch` — Fetch full documentation pages
+
+**Use Cases:**
+- Phase 1: LMStudio/Ollama integration documentation
+- Phase 5: Transformers library best practices
+- Phase 14: Mobile inference frameworks (ONNX Runtime, TensorFlow Lite)
+
+#### Account Info
+- `mcp__claude_ai_Hugging_Face__hf_whoami` — Get authenticated user info
+
+## Web Research
+
+### Tools Available
+- `WebSearch` — Search the web for current information (2026 context)
+- `WebFetch` — Fetch and analyze specific URLs
+
+**Use Cases:**
+- Research current best practices in AI safety (Phase 2)
+- Find Android development patterns (Phase 14)
+- Discover voice visualization libraries (Phase 12)
+- Research avatar systems (Phase 13)
+- Find Discord bot best practices (Phase 10)
+
+## Code & Repository Tools
+
+### Tools Available
+- `Bash` — Execute terminal commands (git, npm, python, etc.)
+- `Glob` — Fast file pattern matching
+- `Grep` — Ripgrep-based content search
+- `Read` — Read file contents
+- `Edit` — Edit files with string replacement
+- `Write` — Create new files
+
+**Use Cases:**
+- All phases: Create and manage project structure
+- All phases: Execute tests and build commands
+- All phases: Manage git commits and history
+
+## Claude Code (GSD) Workflow
+
+### Orchestrators Available
+- `/gsd:new-project` — Initialize project
+- `/gsd:plan-phase N` — Create detailed phase plans
+- `/gsd:execute-phase N` — Execute phase with atomic commits
+- `/gsd:discuss-phase N` — Gather phase context
+- `/gsd:verify-work` — User acceptance testing
+
+### Specialized Agents
+- `gsd-project-researcher` — Domain research (stack, features, architecture, pitfalls)
+- `gsd-phase-researcher` — Phase-specific research
+- `gsd-codebase-mapper` — Analyze and document existing code
+- `gsd-planner` — Create executable phase plans
+- `gsd-executor` — Execute plans with state management
+- `gsd-verifier` — Verify deliverables match requirements
+- `gsd-debugger` — Systematic debugging with checkpoints
+
+## How to Use MCPs in Development
+
+### In Phase Planning
+When creating `/gsd:plan-phase N`:
+- Researchers can use Hugging Face tools to discover libraries and models
+- Use WebSearch for current best practices
+- Query papers for architectural patterns
+
+### In Phase Execution
+When running `/gsd:execute-phase N`:
+- Download models from Hugging Face
+- Use WebFetch for documentation
+- Run Spaces for prototyping UI patterns
+
+### Example Usage by Phase
+
+**Phase 1: Model Interface**
+```
+- mcp__claude_ai_Hugging_Face__model_search
+  Query: "quantized models for local inference"
+  → Find Mistral, Llama, TinyLlama options
+  
+- mcp__claude_ai_Hugging_Face__hf_doc_fetch
+  → Get Hugging Face Transformers documentation
+  
+- WebSearch
+  → Latest LMStudio/Ollama integration patterns
+```
+
+**Phase 2: Safety System**
+```
+- mcp__claude_ai_Hugging_Face__paper_search
+  Query: "code sandboxing, safety verification"
+  → Find relevant research papers
+  
+- WebSearch
+  → Docker security best practices
+```
+
+**Phase 5: Conversation Engine**
+```
+- mcp__claude_ai_Hugging_Face__dataset_search
+  Query: "conversation quality, multi-turn dialogue"
+  
+- mcp__claude_ai_Hugging_Face__paper_search
+  Query: "conversational AI, context management"
+```
+
+**Phase 12: Voice Visualization**
+```
+- mcp__claude_ai_Hugging_Face__space_search
+  Query: "audio visualization, waveform display"
+  → Find working demos
+  
+- mcp__claude_ai_Hugging_Face__model_search
+  Query: "speech recognition, audio models"
+```
+
+**Phase 13: Desktop Avatar**
+```
+- mcp__claude_ai_Hugging_Face__space_search
+  Query: "avatar generation, VRoid, character animation"
+  
+- WebSearch
+  → VRoid SDK documentation
+  → Avatar animation libraries
+```
+
+**Phase 14: Android App**
+```
+- mcp__claude_ai_Hugging_Face__model_search
+  Query: "mobile inference, quantized models, ONNX"
+  
+- WebSearch
+  → Kotlin ML Kit documentation
+  → TensorFlow Lite best practices
+```
+
+## Configuration
+
+Add to `.planning/config.json` to enable MCP usage:
+
+```json
+{
+  "mcp": {
+    "huggingface": {
+      "enabled": true,
+      "authenticated_user": "mystiatech",
+      "default_result_limit": 10
+    },
+    "web_search": {
+      "enabled": true,
+      "domain_restrictions": []
+    },
+    "code_tools": {
+      "enabled": true
+    }
+  }
+}
+```
+
+## Research Output Format
+
+When researchers use MCPs, they produce:
+- `.planning/research/STACK.md` — Technologies and libraries
+- `.planning/research/FEATURES.md` — Capabilities and patterns
+- `.planning/research/ARCHITECTURE.md` — System design patterns
+- `.planning/research/PITFALLS.md` — Common mistakes and solutions
+
+These inform phase planning and implementation.
+
+---
+
+**Updated: 2026-01-26**
+**Next Review: When new MCP servers become available**

.planning/PROJECT.md

@@ -113,7 +113,7 @@ Mai is a real collaborator, not a tool. She learns from you, improves herself, h
 
 **Why this matters:** Current AI systems are static, sterile, and don't actually learn. Users have to explain context every time. Mai is different — she has continuity, personality, agency, and actually improves over time. Starting with a solid local framework means she can eventually run anywhere without cloud dependency.
 
-**Technical environment:** Python-based, local models via LMStudio, git for version control of her own code, Discord API for chat, lightweight local storage for memory. Eventually targeting bare metal on low-end devices.
+**Technical environment:** Python-based, local models via LMStudio/Ollama, git for version control, Discord API for chat, lightweight local storage for memory. Development leverages Hugging Face Hub for model/dataset discovery and research, WebSearch for current best practices. Eventually targeting bare metal on low-end devices.
 
 **User feedback theme:** Traditional chatbots feel rigid and repetitive. Mai should feel like talking to an actual person who gets better at understanding you.
 
@@ -130,6 +130,7 @@ Mai is a real collaborator, not a tool. She learns from you, improves herself, h
 - **Sync consistency**: Desktop and Android instances maintain synchronized state without server
 - **OpenCode-driven**: All development phases executed through Claude Code (GSD workflow)
 - **Python venv**: `.venv` virtual environment for all Python dependencies
+- **MCP-enabled**: Leverages Hugging Face Hub, WebSearch, and code tools for research and implementation
 
 ## Key Decisions
 

.planning/config.json

@@ -13,5 +13,27 @@
     "auto_push": true,
     "push_tags": true,
     "remote": "master"
+  },
+  "mcp": {
+    "huggingface": {
+      "enabled": true,
+      "authenticated_user": "mystiatech",
+      "default_result_limit": 10,
+      "use_for": [
+        "model_discovery",
+        "dataset_research",
+        "paper_search",
+        "documentation_lookup"
+      ]
+    },
+    "web_research": {
+      "enabled": true,
+      "use_for": [
+        "current_practices",
+        "library_research",
+        "architecture_patterns",
+        "security_best_practices"
+      ]
+    }
   }
 }