elease: add multilingual GitHub Pages docs and ship v2.1.0 - 2026-03-31

Author: coderooz

.mcp-project

@@ -0,0 +1 @@
+local-mcp-server

CHANGELOG.md

@@ -6,6 +6,57 @@ This project follows a structured change history to track architectural evolutio
 
 ---
 
+## [v2.1.0] — Documentation Site, Project Identity & Coordination Upgrades
+
+### Added
+
+* Added MCP project intelligence tools:
+
+  * `create_project_map`
+  * `fetch_project_map`
+  
+* Added missing task coordination tools:
+
+  * `assign_task`
+  * `update_task`
+
+* Added richer project map persistence fields:
+
+  * `key_details`
+  * `related_tasks`
+  * `last_verified_at`
+* Added a GitHub Pages-ready documentation site in `docs/` with:
+
+  * installation and setup guidance
+  * integration walkthroughs
+  * MCP tool and API reference
+  * project identity guidance
+  * copyable examples
+  * multilingual language switching
+* Added documentation site assets and metadata:
+
+  * `favicon.ico`
+  * `favicon.svg`
+  * web manifest
+  * robots.txt
+  * sitemap.xml
+* Added project identity migration tooling:
+
+  * `.mcp-project`
+  * `migrate-project-id.js`
+
+### Changed
+
+* Scoped `fetch_tasks` to the active project and added filtering by assignment, creator, status, and limit
+* Scoped messaging retrieval to the active project to avoid cross-project coordination bleed
+* Upgraded project-map storage to upsert by `project + file_path`, making the structure knowledge reusable instead of duplicative
+* Unified project identity derivation across `mcp-shim.js` and direct `mcp-server.js` launches with a shared resolver, `MCP_PROJECT_ROOT`, and project-local override support via `.mcp-project`
+* Updated agent instructions and README to reflect the task-claiming and project-map workflow
+* Updated the validation script to include syntax checking for `docs/app.js`
+* Expanded project bootstrap guidance to include the current tool surface and project-map seeding guidance
+
+---
+
 ## [v2.0.0] — Multi-Agent System & MCP Evolution
 
 Major architectural upgrade introducing a distributed multi-agent system with tasks, messaging, agent coordination, and project intelligence.

PROJECT_MEMORY_BOOTSTRAP.md

@@ -30,8 +30,8 @@ Impact: Keep MCP transport concerns separate from HTTP persistence concerns.
 Type: constraint
 Title: environment-driven identity
 Context: MCP launch configuration
-Details: Agent, project, scope, and server URL are injected through environment variables. MCP_AGENT identifies the client. MCP_PROJECT groups memory by project. MCP_SCOPE controls visibility. Missing values fall back to defaults in mcp-server.js.
-Why: Incorrect launch config produces misleading stored metadata such as unknown agent or default project.
+Details: Agent, project, scope, and server URL are injected through environment variables. MCP_AGENT identifies the client. MCP_PROJECT groups memory by project. MCP_SCOPE controls visibility. Project identity resolution now prefers a project-local override file (`.mcp-project` / `.mcp-project.json`), then project `.env`, then package metadata, then the nearest project-root folder. MCP_PROJECT_ROOT is injected for traceability.
+Why: Incorrect launch config produces misleading stored metadata such as unknown agent or a generic workspace namespace like vscode.
 Impact: Verify launch configuration before debugging memory attribution problems.
 ```
 
@@ -52,9 +52,91 @@ Impact: Preserve index initialization when changing startup or search logic.
 Type: note
 Title: current MCP tool surface
 Context: protocol behavior
-Details: The server exposes store_context, search_context, log_action, get_full_context, start_session, get_agent_instructions, and get_logs. store_context currently accepts only content from the MCP client side.
-Why: Agents should not assume richer tool inputs than the MCP layer actually exposes.
-Impact: Put important structured information directly into the stored content text.
+Details: The server exposes memory tools, task tools (create_task, fetch_tasks, assign_task, update_task), messaging tools, agent registration tools, and project intelligence tools (create_project_map, fetch_project_map). store_context still accepts only content from the MCP client side, but structured project knowledge should now go into the project-map system instead of free-form memory whenever possible.
+Why: Agents should not assume outdated MCP tool limits or skip the structured coordination/project-map layers.
+Impact: Prefer project-map entries for architecture and file-ownership knowledge, and tasks/messages for coordination state.
+```
+
+## Project Map Seeds
+
+Use the following entries to bootstrap the structured project map for this repository.
+
+```text
+Path: .
+Type: project
+Summary: Distributed MCP memory server for multi-agent coordination with MongoDB-backed persistence, task management, messaging, agent registration, and reusable project intelligence.
+Key Details:
+- Core runtime is split between MCP stdio transport and Express persistence API.
+- Project identity is derived from nearest root markers and slugified for stable namespaces.
+- Shared goal is coordination and knowledge reuse across AI agents, not isolated tool execution.
+```
+
+```text
+Path: mcp-server.js
+Type: module
+Summary: MCP stdio entrypoint that defines the tool surface, starts the HTTP API on demand, injects agent/project identity, and forwards tool calls to backend routes.
+Key Details:
+- Uses the same project identity resolver as the shim.
+- Exposes task, messaging, and project-map tools for agents.
+- Waits for the HTTP API before calling backend endpoints.
+```
+
+```text
+Path: server.js
+Type: module
+Summary: Express API and persistence orchestration layer that handles contexts, actions, sessions, agents, tasks, messages, logs, and project-map entries.
+Key Details:
+- Creates Mongo indexes during startup.
+- Enforces project-scoped task/message/project-map retrieval patterns.
+- Upserts project-map entries by project plus file_path.
+```
+
+```text
+Path: mcp.model.js
+Type: module
+Summary: Shared data model definitions for stored entities and memory normalization utilities.
+Key Details:
+- BaseModel injects shared metadata like project, agent, scope, tags, and timestamps.
+- TaskModel now stores blocker/result handoff state.
+- ProjectMapModel stores structural summaries, relationships, key details, and related tasks.
+```
+
+```text
+Path: mcp-shim.js
+Type: module
+Summary: Launch wrapper that derives project identity from the current working tree and starts mcp-server.js with piped stdio.
+Key Details:
+- Sets MCP_PROJECT automatically when not provided.
+- Sets MCP_PROJECT_ROOT for traceability.
+- Keeps protocol-safe stdio wiring between editor/agent and MCP server.
+```
+
+```text
+Path: utils/projectIdentity.js
+Type: module
+Summary: Shared utility for finding the nearest project root marker and deriving a stable slugified project identifier.
+Key Details:
+- Single source of truth for project identity resolution.
+- Used by both the shim and the direct MCP entrypoint.
+- Prevents namespace drift between different launch paths.
+```
+
+```text
+Path: logger.js
+Type: module
+Summary: Writes operational logs to MongoDB and promotes errors into reusable memory entries for future debugging.
+Key Details:
+- Keeps logs out of MCP stdout.
+- Converts runtime errors into global context entries with metadata.
+```
+
+```text
+Path: startMemoryServer.js
+Type: module
+Summary: Ensures the Express API starts only once per process and can be reused by MCP calls safely.
+Key Details:
+- Prevents duplicate API bootstrap inside one runtime.
+- Resets startup promise on failure so startup can be retried.
 ```
 
 ## Suggested Seed Actions

README.md

@@ -62,6 +62,7 @@ MongoDB (Persistence Layer)
 - Work coordination between agents
 - Task lifecycle:
   - pending → in_progress → completed / blocked
+- Supports claiming ownership and status handoffs
 - Prevents duplication of work
 
 ---
@@ -89,6 +90,7 @@ MongoDB (Persistence Layer)
   - dependencies
   - relationships
   - architecture patterns
+  - key implementation details and related tasks
 - Enables system-level reasoning
 
 ---
@@ -122,16 +124,25 @@ MongoDB (Persistence Layer)
 | Tool | Description |
 |------|------------|
 | `create_task` | Create task |
-| `fetch_tasks` | Get tasks |
-| *(API)* `/task/assign` | Assign task |
+| `fetch_tasks` | Get project-scoped tasks with filters |
+| `assign_task` | Claim or assign task ownership |
+| `update_task` | Update task status, blockers, or results |
 
 ---
 
 ### 💬 Messaging Tools
 | Tool | Description |
 |------|------------|
 | `send_message` | Send message |
-| `request_messages` | Fetch messages |
+| `request_messages` | Fetch project-scoped messages |
+
+---
+
+### 🗺 Project Map Tools
+| Tool | Description |
+|------|------------|
+| `create_project_map` | Store reusable project structure intelligence |
+| `fetch_project_map` | Retrieve project structure intelligence |
 
 ---
 
@@ -204,6 +215,36 @@ mcp-shim.js
 * Zero per-project config
 * Clean multi-project isolation
 
+### Project Identity
+
+Both `mcp-shim.js` and direct `mcp-server.js` launches now derive the project name from the same resolver and slugify it into a stable `MCP_PROJECT` value. Resolution order is:
+
+1. `.mcp-project` or `.mcp-project.json` in the project root
+2. `MCP_PROJECT` from the project `.env`
+3. `package.json` name / `mcpProject`
+4. nearest project-root folder name
+
+The shim also injects `MCP_PROJECT_ROOT` so agents can trace which workspace produced a memory entry. This repository now pins its identifier with `.mcp-project` and `.env` to `local-mcp-server`, so it will not inherit a generic workspace name like `vscode`.
+
+If you already have old documents stored under another project name such as `vscode`, run `npm run migrate:project-id -- vscode local-mcp-server` to rewrite existing records in MongoDB.
+
+---
+
+## 📚 Documentation Site
+
+A GitHub Pages-ready documentation site now lives in the [`docs/`](./docs/) folder.
+
+It includes:
+
+* installation and setup guidance
+* editor and MCP integration patterns
+* tool and API reference
+* project identity and migration guidance
+* copyable examples
+* multilingual navigation
+
+To publish it, enable GitHub Pages for the repository branch and select the `/docs` folder as the source.
+
 ---
 
 ## 🧠 Execution Model (v2)

agent-instruction.js

@@ -40,6 +40,9 @@ MCP SERVER REALITY
 - store_context accepts ONLY: { content }
 - search_context returns ranked summaries
 - get_full_context returns structured JSON
+- fetch_tasks returns project-scoped task lists with assignment/status filters
+- send_message and request_messages are project-scoped
+- project structure is stored via create_project_map / fetch_project_map
 - get_logs = backend debugging ONLY
 
 Do NOT assume unsupported fields or hidden features.
@@ -109,14 +112,19 @@ Use when:
 
 Behavior:
 - Prefer existing project_map over re-analysis
+- Use fetch_project_map before remapping a project area
 - Update ONLY when:
   - structure changes
   - new modules introduced
+- Persist updates with create_project_map
+- file_path should be relative to project root
+- Use "." for project-level summaries
 - Do NOT store trivial file listings
 - Store:
   - relationships
   - dependencies
   - architecture patterns
+  - key details that unblock future agents
 
 Goal:
 → persistent system-level awareness across agents
@@ -175,6 +183,15 @@ Use create_task when:
 - system impact
 - coordination required
 
+Use assign_task when:
+- claiming ownership
+- routing work to another agent
+
+Use update_task when:
+- status changes
+- blocked reason discovered
+- handoff result is ready
+
 Before acting:
 → ALWAYS fetch_tasks
 
@@ -246,8 +263,10 @@ start_session → track multi-step work
 get_logs → backend debugging  
 
 create_task / fetch_tasks → task system  
+assign_task / update_task → task coordination  
 send_message / request_messages → communication  
 register_agent / list_agents → agent system  
+create_project_map / fetch_project_map → project structure intelligence  
 
 Rules:
 - Do NOT use blindly

docs/.nojekyll

@@ -0,0 +1 @@
+