Yandex Tracker MCP

Instructions

Implementation Reference

• mcp_tracker/mcp/tools.py:257-291 (handler)

  The main MCP tool handler for 'issues_find' that handles parameters, calls the underlying tracker client, processes results (e.g., clears descriptions if not needed, filters fields), and returns the list of issues.

  @mcp.tool(description="Find Yandex Tracker issues by queue and/or created date")
  async def issues_find(
      ctx: Context[Any, AppContext],
      query: YTQuery,
      include_description: Annotated[
          bool,
          Field(
              description="Whether to include issue description in the issues result. It can be large, so use only when needed.",
          ),
      ] = False,
      fields: Annotated[
          list[IssueFieldsEnum] | None,
          Field(
              description="Fields to include in the response. In order to not pollute context window - select "
              "appropriate fields beforehand. Not specifying fields will return all available."
          ),
      ] = None,
      page: PageParam = 1,
      per_page: PerPageParam = 100,
  ) -> list[Issue]:
      issues = await ctx.request_context.lifespan_context.issues.issues_find(
          query=query,
          per_page=per_page,
          page=page,
          auth=get_yandex_auth(ctx),
      )
  
      if not include_description:
          for issue in issues:
              issue.description = None  # Clear description to save context
  
      if fields is not None:
          set_non_needed_fields_null(issues, {f.name for f in fields})
  
      return issues

• mcp_tracker/mcp/params.py:50-92 (schema)

  Pydantic schema definition for the 'query' parameter of issues_find tool, including detailed description of Yandex Tracker Query Language syntax.

  YTQuery = Annotated[
      str,
      Field(
          description=(
              """Search query to filter issues using Yandex Tracker Query.\n"""
              """# General instructions\n"""
              """1. To search by a specific field use the following syntax: `Description: "some issue description"`\n"""
              """2. Multiple fields should be separated by space: `Description: "some issue description" Created: today()`\n"""
              """3. If you need to specify multiple values for the same field - provide them using comma (,), e.g.: `author: "vpupkin","iivanov"`\n"""
              """4. You may specify multiple conditions and combine them using `AND` and `OR` statements, e.g. `<param_1>: "<value_1>" AND <param_2>: "<value_2>"`\n"""
              """5. You may use brackets for complex logical expressions\n"""
              """6. To find issues with exact string matching in the field use this syntax: `Summary: #"Version 2.0"`. If you need to pass special characters - you must escape them using `\\` symbol\n"""
              """7. To find issues that don't contain the specified text use this syntax: `Summary: !"Version 2.0"`. If you need to pass special characters - you must escape them using `\\` symbol\n"""
              """8. If you need to search by local queue field use the following syntax: `<QUEUE>.<LOCAL_FIELD_KEY>: "<value>", where <QUEUE> is a queue key, <LOCAL_FIELD_KEY> is a local field's key from the `queue_get_local_fields` tool result.\n"""
              """9. For dates use the format YYYY-MM-DD.\n"""
              """10. For numerical values you may use comparison operators (>, <, >=, <=): `<param>: ><value>`.\n"""
              """11. To sort the result specify the `Sort By` directive (you may provide ASC or DESC for the sort order): `"Sort By": Created ASC`.\n"""
              """12. For Assignee field and any other field representing a user (such as Author and others) always use username and not name.\n"""
              """# Functions\n"""
              """These functions may be used, for example: `Created: week()` - return issues created on the current week"\n"""
              """* `empty()` - empty value\n"""
              """* `notEmpty()` - not empty value\n"""
              """* `now()` - current time\n"""
              """* `today()` - current date\n"""
              """* `week()` - current week\n"""
              """* `month()` - current month\n"""
              """* `quarter()` - current quarter\n"""
              """* `year()` - current year\n"""
              """* `unresolved()` - there is no resolution\n"""
              """* `me()` - currently logged in user\n"""
              """# Examples\n"""
              """Find issues in a specific queue: `"Queue": "PROJ"`\n"""
              """Find issues by an assignee: `"Assignee": "i.ivanov"`\n"""
              """Find not resolved (open, in progress) issues: `"Resolution": unresolved()`\n"""
              """Find issues in specific status: `"Status": "Открыт", "В работе"`\n"""
              """Find issues created in a specific range: `"Created": "2017-01-01".."2017-01-30"`\n"""
              """Find issues created by currently logged in user: `"Author": me()"`\n"""
              """Find issues assigned to currently logged in user: `"Assignee": me()"`\n"""
              """Find issues created no earlier than 1 week and 1 day before today: `Created: > today() - "1w 1d"`\n"""
              """Complete instructions page is available here: https://yandex.ru/support/tracker/ru/user/query-filter\n"""
          )
      ),
  ]

• mcp_tracker/mcp/server.py:166-166 (registration)

  The call to register_tools which defines and registers the 'issues_find' tool (along with other tools) to the FastMCP server instance.

  register_tools(settings, mcp)

• mcp_tracker/tracker/proto/issues.py:24-31 (helper)

  Protocol definition for the underlying issues_find method called by the MCP handler.

  async def issues_find(
      self,
      query: str,
      *,
      per_page: int = 15,
      page: int = 1,
      auth: YandexAuth | None = None,
  ) -> list[Issue]: ...