tpm-mcp

Instructions

Implementation Reference

• src/tpm_mcp/server.py:210-255 (registration)

  Registration of the 'ticket_search' tool in the list_tools() function, including name, description, and JSON inputSchema.
  Tool( name="ticket_search", description="""PROJECT MANAGEMENT (TPM): Search tickets by keyword. USE THIS TOOL WHEN: - User asks "find tickets about X" or "search for Y" - Looking for tickets by keywords in title or description - Need to discover relevant tickets across projects Searches title and description. Supports prefix matching (e.g., "org" matches "organization"). Case-insensitive. All filters are combinable.""", inputSchema={ "type": "object", "properties": { "query": { "type": "string", "description": "Search query (keywords to search in title/description)", }, "project_id": { "type": "string", "description": "Filter by project ID (optional, case-insensitive)", }, "status": { "type": "string", "enum": ["backlog", "planned", "in-progress", "done", "blocked"], "description": "Filter by status (optional)", }, "priority": { "type": "string", "enum": ["critical", "high", "medium", "low"], "description": "Filter by priority (optional)", }, "tags": { "type": "array", "items": {"type": "string"}, "description": "Filter by tags - ticket must have all specified tags (optional)", }, "limit": { "type": "integer", "description": "Maximum results to return (default: 20, max: 100)", "default": 20, }, }, "required": ["query"], }, ),
• src/tpm_mcp/server.py:560-579 (handler)

  Handler logic in _handle_tool() that processes arguments, normalizes them, calls db.search_tickets(), and formats the JSON response.
  if name == "ticket_search": limit = min(args.get("limit", 20), 100) status = TicketStatus(args["status"]) if args.get("status") else None priority = Priority(args["priority"]) if args.get("priority") else None results = db.search_tickets( query=args["query"], project_id=args.get("project_id"), status=status, priority=priority, tags=args.get("tags"), limit=limit, ) return _json({ "results": results, "total": len(results), "query": args["query"], })
• src/tpm_mcp/db.py:438-524 (helper)

  Core implementation of ticket search using SQLite FTS5 full-text search on titles/descriptions, with dynamic filters for project, status, priority, tags, and limit. Returns highlighted snippets.
  def search_tickets( self, query: str, project_id: str | None = None, status: TicketStatus | None = None, priority: Priority | None = None, tags: list[str] | None = None, limit: int = 20, ) -> list[dict]: """Search tickets using full-text search with optional filters. Args: query: Search query (supports prefix matching) project_id: Filter by project ID (case-insensitive) status: Filter by ticket status priority: Filter by priority level tags: Filter by tags (ticket must have all specified tags) limit: Maximum results to return (default 20) Returns: List of dicts with: id, title, project_id, status, priority, tags, snippet """ if not query or not query.strip(): return [] # Build FTS5 query with prefix matching for each term terms = query.strip().split() fts_query = " ".join(f"{term}*" for term in terms) # Build the SQL query with joins and filters sql = """ SELECT t.id, t.title, t.project_id, t.status, t.priority, t.tags, snippet(tickets_fts, 1, '<b>', '</b>', '...', 32) as snippet FROM tickets_fts JOIN tickets t ON tickets_fts.ticket_id = t.id WHERE tickets_fts MATCH ? """ params: list = [fts_query] # Add filters if project_id: project_id = self._normalize_id(project_id) sql += " AND LOWER(t.project_id) = ?" params.append(project_id) if status: sql += " AND t.status = ?" params.append(status.value) if priority: sql += " AND t.priority = ?" params.append(priority.value) if tags: # Check that ticket has all specified tags using json_each for tag in tags: sql += " AND EXISTS (SELECT 1 FROM json_each(t.tags) WHERE value = ?)" params.append(tag) # Order by relevance (FTS5 rank) and limit sql += " ORDER BY rank LIMIT ?" params.append(limit) try: rows = self.conn.execute(sql, params).fetchall() return [ { "id": r["id"], "title": r["title"], "project_id": r["project_id"], "status": r["status"], "priority": r["priority"], "tags": _from_json(r["tags"]), "snippet": r["snippet"], } for r in rows ] except Exception: # Handle FTS5 syntax errors gracefully return []