tpm-mcp

Instructions

Implementation Reference

• src/tpm_mcp/server.py:658-670 (handler)

  MCP tool handler for 'task_create': parses input arguments, validates with TaskCreate model, delegates to database layer, returns success confirmation.

  if name == "task_create":
      task = db.create_task(
          TaskCreate(
              ticket_id=args["ticket_id"],
              title=args["title"],
              details=args.get("details"),
              status=TaskStatus(args.get("status", "pending")),
              priority=Priority(args.get("priority", "medium")),
              complexity=Complexity(args.get("complexity", "medium")),
          )
      )
      # Return minimal confirmation to avoid context bleed
      return f"Created task: {task.id} - {task.title} [{task.status.value}]"

• src/tpm_mcp/server.py:292-327 (registration)

  Registers the 'task_create' tool with the MCP server, defining its name, description, and JSON schema for input validation.

          Tool(
              name="task_create",
              description="""PROJECT MANAGEMENT (TPM): Create a task (sub-item) under a ticket.
  
  USE THIS TOOL WHEN:
  - Breaking down a ticket into smaller tasks
  - User asks to add implementation steps
  - Creating a work breakdown structure""",
              inputSchema={
                  "type": "object",
                  "properties": {
                      "ticket_id": {"type": "string", "description": "Parent ticket ID"},
                      "title": {"type": "string", "description": "Task title"},
                      "details": {
                          "type": "string",
                          "description": "Task details/implementation notes",
                      },
                      "status": {
                          "type": "string",
                          "enum": ["pending", "in-progress", "done", "blocked"],
                          "description": "Task status (default: pending)",
                      },
                      "priority": {
                          "type": "string",
                          "enum": ["critical", "high", "medium", "low"],
                          "description": "Priority (default: medium)",
                      },
                      "complexity": {
                          "type": "string",
                          "enum": ["simple", "medium", "complex"],
                          "description": "Complexity estimate (default: medium)",
                      },
                  },
                  "required": ["ticket_id", "title"],
              },
          ),

• src/tpm_mcp/models.py:130-139 (schema)

  Pydantic model defining the structure and validation for task creation input data used in the handler.

  class TaskCreate(BaseModel):
      ticket_id: str
      title: str
      details: str | None = None
      status: TaskStatus = TaskStatus.PENDING
      priority: Priority = Priority.MEDIUM
      complexity: Complexity = Complexity.MEDIUM
      acceptance_criteria: list[str] | None = None
      metadata: dict[str, Any] | None = None

• src/tpm_mcp/db.py:575-621 (helper)

  Core database helper: generates unique task ID based on ticket, inserts task record into SQLite 'tasks' table, handles JSON serialization for metadata fields, returns Task model instance.

  def create_task(self, data: TaskCreate) -> Task:
      # Get ticket to extract prefix
      ticket = self.get_ticket(data.ticket_id)
      if not ticket:
          raise ValueError(f"Ticket {data.ticket_id} not found")
  
      # Count existing tasks for this ticket to generate task number
      count = self.conn.execute(
          "SELECT COUNT(*) FROM tasks WHERE ticket_id = ?", (data.ticket_id,)
      ).fetchone()[0]
  
      # Generate task ID like TASK-TICKET-001-1
      ticket_num = ticket.id.replace("TICKET-", "").replace("FEAT-", "").replace("ISSUE-", "")
      id = f"TASK-{ticket_num}-{count + 1}"
      now = self._now()
  
      self.conn.execute(
          """INSERT INTO tasks (id, ticket_id, title, details, status, priority, complexity,
             created_at, acceptance_criteria, metadata)
             VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)""",
          (
              id,
              data.ticket_id,
              data.title,
              data.details,
              data.status.value,
              data.priority.value,
              data.complexity.value,
              now,
              _to_json(data.acceptance_criteria),
              _to_json(data.metadata),
          ),
      )
      self.conn.commit()
      return Task(
          id=id,
          ticket_id=data.ticket_id,
          title=data.title,
          details=data.details,
          status=data.status,
          priority=data.priority,
          complexity=data.complexity,
          created_at=datetime.fromisoformat(now),
          acceptance_criteria=data.acceptance_criteria,
          metadata=data.metadata,
      )