fetch_initiative

Instructions

Implementation Reference

• src/mk_plan_master/tools/initiatives.py:68-101 (handler)

  The main tool handler function: extracts initiative_id from arguments, resolves the active source adapter, calls source.fetch(), and returns the full Initiative record (converted to dict) or a structured error.

  def fetch_initiative_tool(arguments: dict) -> dict[str, Any]:
      initiative_id = arguments.get("initiative_id") or arguments.get("id")
      if not initiative_id:
          return _error(
              "initiative_id is required",
              retryable=False,
              hint="Pass initiative_id (or id) — typically discovered via list_initiatives.",
          )
  
      try:
          source = get_source(SOURCE_NAME)
      except ValueError as exc:
          return _error(
              str(exc),
              retryable=False,
              hint="Set PLAN_SOURCE to one of the available adapters.",
          )
  
      try:
          initiative = source.fetch(str(initiative_id))
      except ValueError as exc:
          return _error(
              str(exc),
              retryable=False,
              hint="Run list_initiatives first to confirm the id exists in the active source.",
          )
      except Exception as exc:
          return _error(
              f"{type(exc).__name__}: {exc}",
              retryable=True,
              hint="Transient adapter error — retry, then check adapter credentials / network.",
          )
  
      return asdict(initiative)

• src/mk_plan_master/server.py:91-106 (schema)

  Tool registration with inputSchema — defines 'initiative_id' as a required string property and includes the description of what the tool returns.

  Tool(
      name="fetch_initiative",
      description=(
          "Pull a single initiative by id from the active source. Returns "
          "the full Initiative record {id, source, title, body, url, status, "
          "labels, raw_metadata}. raw_metadata holds scoring inputs (reach / "
          "impact / confidence / effort / okr) plus any source-specific "
          "fields. Pair with score_initiative to get a RICE / Impact-Effort rank."
      ),
      inputSchema={
          "type": "object",
          "properties": {
              "initiative_id": {"type": "string"},
          },
          "required": ["initiative_id"],
      },

• src/mk_plan_master/server.py:36-39 (registration)

  Dispatch table mapping 'fetch_initiative' string to the fetch_initiative_tool function.

  _DISPATCH: dict[str, Callable[[dict], dict]] = {
      "get_plan_source_info": initiatives_tools.get_plan_source_info_tool,
      "list_initiatives": initiatives_tools.list_initiatives_tool,
      "fetch_initiative": initiatives_tools.fetch_initiative_tool,

• src/mk_plan_master/tools/scoring.py:116-118 (helper)

  Internal _fetch_initiative helper used by the scoring tool — also calls get_source + source.fetch, re-used from the scoring module.

  def _fetch_initiative(initiative_id: str) -> Initiative:
      source = get_source(SOURCE_NAME)
      return source.fetch(initiative_id)

• src/mk_plan_master/adapters/markdown_local.py:139-166 (helper)

  MarkdownLocalAdapter.fetch() — the default adapter's implementation that parses frontmatter from .md files and returns the full Initiative dataclass with raw_metadata.

  def fetch(self, initiative_id: str) -> Initiative:
      for path in _initiative_files():
          meta, body = _parse_frontmatter(path.read_text(encoding="utf-8"))
          if _initiative_id_from(meta, path) != initiative_id:
              continue
  
          labels = meta.get("labels") or []
          if isinstance(labels, str):
              labels = [labels]
  
          raw_metadata = {
              k: v for k, v in meta.items() if k not in _RESERVED_KEYS
          }
  
          return Initiative(
              id=initiative_id,
              source=self.name,
              title=str(meta.get("title") or initiative_id),
              body=body.strip(),
              url=str(path),
              status=str(meta.get("status") or ""),
              labels=list(labels),
              raw_metadata=raw_metadata,
          )
  
      raise ValueError(
          f"initiative_id={initiative_id!r} not found under {INITIATIVES_DIR}"
      )