feat: introduce agent presence management and add vision/sketch fields and tools to context

Author: ChesterRa

.gitignore

@@ -42,3 +42,6 @@ build/
 
 # Local development
 context/
+
+# DOC
+docs/plan

IMPLEMENTATION_VERSION_TRACKING.md

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "ccontext-mcp"
-version = "0.1.4"
+version = "0.1.5"
 description = "MCP server for AI agents to manage project execution context"
 readme = "README.md"
 license = "MIT"

pyproject.toml

@@ -18,6 +18,13 @@ class MilestoneStatus(str, Enum):
     PENDING = "pending"
 
 
+class AgentStatus(str, Enum):
+    """Agent presence status values."""
+    ACTIVE = "active"
+    IDLE = "idle"
+    OFFLINE = "offline"
+
+
 class TaskStatus(str, Enum):
     """Task status values."""
     PLANNED = "planned"
@@ -124,11 +131,36 @@ def progress(self) -> float:
 
 class Context(BaseModel):
     """The main context structure stored in context.yaml."""
+    vision: Optional[str] = Field(default=None, description="Project vision/goal - what we're building")
+    sketch: Optional[str] = Field(default=None, description="Execution blueprint - architecture, current phase, upcoming work (markdown)")
     milestones: list[Milestone] = Field(default_factory=list, description="Project milestones")
     notes: list[Note] = Field(default_factory=list, description="Notes")
     references: list[Reference] = Field(default_factory=list, description="References")
 
 
+# =============================================================================
+# Presence Models (stored in presence.yaml, gitignored)
+# =============================================================================
+
+class AgentPresence(BaseModel):
+    """A single agent's presence status."""
+    id: str = Field(..., description="Agent ID (e.g., peer-a, peer-b)")
+    status: AgentStatus = Field(default=AgentStatus.IDLE, description="Current status")
+    task: Optional[str] = Field(default=None, description="Current task ID (e.g., T003)")
+    step: Optional[str] = Field(default=None, description="Current step ID (e.g., S2)")
+    message: Optional[str] = Field(default=None, description="Free-form status message")
+    updated_at: str = Field(
+        default_factory=lambda: datetime.now(timezone.utc).isoformat().replace("+00:00", "Z"),
+        description="Last update timestamp"
+    )
+
+
+class PresenceData(BaseModel):
+    """The presence data structure stored in presence.yaml."""
+    agents: list[AgentPresence] = Field(default_factory=list, description="Agent presence list")
+    heartbeat_timeout_seconds: int = Field(default=300, description="Timeout for stale detection")
+
+
 # =============================================================================
 # Response Models
 # =============================================================================
@@ -143,6 +175,8 @@ class TasksSummary(BaseModel):
 
 class ContextResponse(BaseModel):
     """Response structure for get_context tool."""
+    vision: Optional[str] = None
+    sketch: Optional[str] = None
     milestones: list[dict] = Field(default_factory=list)
     notes: list[dict] = Field(default_factory=list)
     references: list[dict] = Field(default_factory=list)

src/ccontext_mcp/schema.py

@@ -30,6 +30,69 @@ async def list_tools() -> list[Tool]:
                     "required": [],
                 },
             ),
+            # Vision/Sketch tools
+            Tool(
+                name="update_vision",
+                description=TOOL_DESCRIPTIONS["update_vision"],
+                inputSchema={
+                    "type": "object",
+                    "properties": {
+                        "vision": {"type": "string", "description": "Project vision statement"},
+                    },
+                    "required": ["vision"],
+                },
+            ),
+            Tool(
+                name="update_sketch",
+                description=TOOL_DESCRIPTIONS["update_sketch"],
+                inputSchema={
+                    "type": "object",
+                    "properties": {
+                        "sketch": {"type": "string", "description": "Execution blueprint (markdown)"},
+                    },
+                    "required": ["sketch"],
+                },
+            ),
+            # Presence tools
+            Tool(
+                name="get_presence",
+                description=TOOL_DESCRIPTIONS["get_presence"],
+                inputSchema={
+                    "type": "object",
+                    "properties": {},
+                    "required": [],
+                },
+            ),
+            Tool(
+                name="update_my_status",
+                description=TOOL_DESCRIPTIONS["update_my_status"],
+                inputSchema={
+                    "type": "object",
+                    "properties": {
+                        "agent_id": {"type": "string", "description": "Your agent ID (e.g., peer-a)"},
+                        "status": {
+                            "type": "string",
+                            "enum": ["active", "idle", "offline"],
+                            "description": "Your current status",
+                        },
+                        "task": {"type": "string", "description": "Current task ID (e.g., T003)"},
+                        "step": {"type": "string", "description": "Current step ID (e.g., S2)"},
+                        "message": {"type": "string", "description": "Status message"},
+                    },
+                    "required": ["agent_id", "status"],
+                },
+            ),
+            Tool(
+                name="set_idle",
+                description=TOOL_DESCRIPTIONS["set_idle"],
+                inputSchema={
+                    "type": "object",
+                    "properties": {
+                        "agent_id": {"type": "string", "description": "Your agent ID (e.g., peer-a)"},
+                    },
+                    "required": ["agent_id"],
+                },
+            ),
             # Milestone tools
             Tool(
                 name="create_milestone",
@@ -283,6 +346,26 @@ async def call_tool(name: str, arguments: dict[str, Any]) -> list[TextContent]:
             if name == "get_context":
                 result = tools.get_context()
 
+            # Vision/Sketch tools
+            elif name == "update_vision":
+                result = tools.update_vision(vision=arguments["vision"])
+            elif name == "update_sketch":
+                result = tools.update_sketch(sketch=arguments["sketch"])
+
+            # Presence tools
+            elif name == "get_presence":
+                result = tools.get_presence()
+            elif name == "update_my_status":
+                result = tools.update_my_status(
+                    agent_id=arguments["agent_id"],
+                    status=arguments["status"],
+                    task=arguments.get("task"),
+                    step=arguments.get("step"),
+                    message=arguments.get("message"),
+                )
+            elif name == "set_idle":
+                result = tools.set_idle(agent_id=arguments["agent_id"])
+
             # Milestone tools
             elif name == "create_milestone":
                 result = tools.create_milestone(