Yellhorn MCP

Instructions

Implementation Reference

• yellhorn_mcp/server.py:240-262 (registration)

  MCP tool registration decorator defining the create_workplan tool with name, description, and input schema via parameters.

  @mcp.tool(
      name="create_workplan",
      description="""Creates a GitHub issue with a detailed implementation plan.
  
  This tool will:
  1. Create a GitHub issue immediately with the provided title and description
  2. Launch a background AI process to generate a comprehensive workplan
  3. Update the issue with the generated workplan once complete
  
  The AI will analyze your entire codebase (respecting .gitignore) to create a detailed plan with:
  - Specific files to modify/create
  - Code snippets and examples
  - Step-by-step implementation instructions
  - Testing strategies
  
  Codebase reasoning modes:
  - "full": Complete file contents (most comprehensive)
  - "lsp": Function signatures and docstrings only (lighter weight)
  - "file_structure": Directory tree only (fastest)
  - "none": No codebase context
  
  Returns the created issue URL and number immediately.""",
  )

• yellhorn_mcp/server.py:263-389 (handler)

  The main handler function for the create_workplan tool. It creates the GitHub issue immediately, adds a submission metadata comment, launches an asynchronous background task using process_workplan_async for AI generation, and returns the issue URL and number.

  async def create_workplan(
      ctx: Context,
      title: str,
      detailed_description: str,
      codebase_reasoning: str = "full",
      debug: bool = False,
      disable_search_grounding: bool = False,
  ) -> str:
      """Creates a GitHub issue with a detailed implementation plan based on codebase analysis.
  
      Args:
          ctx: Server context.
          title: Title for the GitHub issue and workplan.
          detailed_description: Detailed description of what needs to be implemented.
          codebase_reasoning: Reasoning mode for codebase analysis:
                 - "full": Include complete file contents (most comprehensive)
                 - "lsp": Include only function signatures and docstrings (lighter weight)
                 - "file_structure": Include only directory/file structure (fastest)
                 - "none": No codebase context (relies only on description)
          debug: If True, adds a comment to the issue with the full prompt used for generation.
          disable_search_grounding: If True, disables Google Search Grounding for this request.
  
      Returns:
          JSON string containing the issue URL and number.
  
      Raises:
          YellhornMCPError: If issue creation fails.
      """
      try:
          repo_path: Path = ctx.request_context.lifespan_context["repo_path"]
  
          # Handle search grounding override if specified
          original_search_grounding = ctx.request_context.lifespan_context.get(
              "use_search_grounding", True
          )
          if disable_search_grounding:
              ctx.request_context.lifespan_context["use_search_grounding"] = False
              await ctx.log(
                  level="info",
                  message="Search grounding temporarily disabled for this request",
              )
  
          # Create the GitHub issue first
          issue_data = await create_github_issue(repo_path, title, detailed_description)
          issue_number = issue_data["number"]
          issue_url = issue_data["url"]
  
          await ctx.log(
              level="info",
              message=f"Created GitHub issue #{issue_number}",
          )
  
          # Extract URLs from the description
          submitted_urls = extract_urls(detailed_description)
  
          # Add submission comment
          submission_metadata = SubmissionMetadata(
              status="Generating workplan...",
              model_name=ctx.request_context.lifespan_context["model"],
              search_grounding_enabled=ctx.request_context.lifespan_context.get(
                  "use_search_grounding", False
              ),
              yellhorn_version=__version__,
              submitted_urls=submitted_urls if submitted_urls else None,
              codebase_reasoning_mode=codebase_reasoning,
              timestamp=datetime.now(timezone.utc),
          )
  
          submission_comment = format_submission_comment(submission_metadata)
          await add_issue_comment(repo_path, issue_number, submission_comment)
  
          # Skip AI workplan generation if codebase_reasoning is "none"
          if codebase_reasoning != "none":
              llm_manager = ctx.request_context.lifespan_context.get("llm_manager")
              model = ctx.request_context.lifespan_context["model"]
              reasoning_effort = ctx.request_context.lifespan_context.get("reasoning_effort")
  
              # Store codebase_reasoning in context for process_workplan_async
              ctx.request_context.lifespan_context["codebase_reasoning"] = codebase_reasoning
  
              # Launch background task to process the workplan with AI
              await ctx.log(
                  level="info",
                  message=f"Launching background task to generate workplan with AI model {model}",
              )
              start_time = datetime.now(timezone.utc)
  
              asyncio.create_task(
                  process_workplan_async(
                      repo_path,
                      llm_manager,
                      model,
                      title,
                      issue_number,
                      codebase_reasoning,
                      detailed_description,
                      debug=debug,
                      disable_search_grounding=disable_search_grounding,
                      reasoning_effort=reasoning_effort,
                      _meta={
                          "original_search_grounding": original_search_grounding,
                          "start_time": start_time,
                          "submitted_urls": submitted_urls,
                      },
                      ctx=ctx,
                      github_command_func=ctx.request_context.lifespan_context.get(
                          "github_command_func"
                      ),
                      git_command_func=ctx.request_context.lifespan_context.get("git_command_func"),
                  )
              )
          else:
              await ctx.log(
                  level="info",
                  message="Skipping AI workplan generation (codebase_reasoning='none')",
              )
  
          # Restore original search grounding setting if modified
          if disable_search_grounding:
              ctx.request_context.lifespan_context["use_search_grounding"] = original_search_grounding
  
          # Return the issue URL and number as JSON
          return json.dumps({"issue_url": issue_url, "issue_number": issue_number})
  
      except Exception as e:
          raise YellhornMCPError(f"Failed to create workplan: {str(e)}")

• yellhorn_mcp/processors/workplan_processor.py:354-595 (helper)

  Supporting helper function called asynchronously by the handler. It gathers codebase context based on reasoning mode, constructs a detailed prompt for workplan generation, and invokes the LLM via _generate_and_update_issue to generate the content and update the GitHub issue with metrics and citations.

  async def process_workplan_async(
      repo_path: Path,
      llm_manager: LLMManager,
      model: str,
      title: str,
      issue_number: str,
      codebase_reasoning: str,
      detailed_description: str,
      debug: bool = False,
      disable_search_grounding: bool = False,
      _meta: dict[str, object] | None = None,
      ctx: Context | None = None,
      github_command_func: Callable | None = None,
      git_command_func: Callable | None = None,
      reasoning_effort: ReasoningEffort | None = None,
  ) -> None:
      """Generate a workplan asynchronously and update the GitHub issue.
  
      Args:
          repo_path: Path to the repository.
          llm_manager: LLM Manager instance.
          model: Model name to use (Gemini or OpenAI).
          title: Title for the workplan.
          issue_number: GitHub issue number to update.
          codebase_reasoning: Reasoning mode to use for codebase analysis.
          detailed_description: Detailed description for the workplan.
          debug: If True, add a comment with the full prompt used for generation.
          disable_search_grounding: If True, disables search grounding for this request.
          _meta: Optional metadata from the caller.
          ctx: Optional context for logging.
          github_command_func: Optional GitHub command function (for mocking).
          git_command_func: Optional Git command function (for mocking).
          reasoning_effort: Optional reasoning effort to apply for supported models.
      """
      try:
          # Create a simple logging function that uses ctx if available
          def context_log(msg: str):
              if ctx:
                  asyncio.create_task(ctx.log(level="info", message=msg))
  
          # Get codebase info based on reasoning mode
          # Calculate token limit for codebase context (70% of model's context window)
          token_counter = TokenCounter()
          model_limit = token_counter.get_model_limit(model)
          # Reserve tokens for prompt template, task details, and response
          # Estimate: prompt template ~1000, task details ~500, safety margin for response ~4000
          codebase_token_limit = int((model_limit - 5500) * 0.7)
  
          codebase_info, _ = await get_codebase_context(
              repo_path,
              codebase_reasoning,
              context_log,
              token_limit=codebase_token_limit,
              model=model,
              git_command_func=git_command_func,
          )
  
          # Construct prompt
          prompt = f"""You are a senior software architect and technical writer.  
  Your task is to output a GitHub-issue–ready **work-plan** that fully complies with the “Strong Work-Plan Rules” and the “Gap-Fix Guidelines” below.  
  The answer you return will be copied verbatim into a GitHub issue, so structure, order and precision matter.
  
  CONTEXT
  ───────────────────
  Multi-file snippet of the current repo (trimmed for length)
  {codebase_info}
  
  One-line task title
  {title}
  
  Product / feature description from the PM
  {detailed_description}
  
  GLOBAL TONE & STYLE
  ───────────────────
  • Write as one senior engineer explaining to another.  
  • Zero “TODO”, “placeholder”, or speculative wording—everything must be concrete and actionable.  
  • Be self-sufficient: an unfamiliar engineer can execute the plan end-to-end without additional guidance.  
  • All headings and check-box bullets must render correctly in GitHub Markdown.  
  • Keep line length ≤ 120 characters where feasible.
  
  TOP-LEVEL SECTIONS  (DO NOT ADD, REMOVE, OR RE-ORDER)
  ──────────────────────────────────────────────────────
  ## Summary  
  ## Technical Details  
  ## Architecture  
  ## Completion Criteria & Metrics  
  ## References  
  ## Implementation Steps  
  ## Global Test Strategy  
  ## Files to Modify  
  ## New Files to Create  
  
  MANDATORY CONTENT PER SECTION
  ─────────────────────────────
  ## Summary   (≤ 5 sentences)
  1 . Problem – one sentence that states the issue or feature.  
  2 . Proposed solution – what will be built.  
  3 . Why it matters – business or technical impact.  
  4 . Success criteria – concise, measurable, single sentence.  
  5 . Main subsystems touched.
  
  ## Technical Details
  • Languages, frameworks, min versions.  
  • “External Dependencies” sub-section:  
    – List every new third-party package AND specify how it will be introduced (e.g., `pyproject.toml` stanza, Dockerfile line).  
  • Dependency management & pinning strategy (uv, npm, go-mods, etc.).  
  • Build, lint, formatting, type-checking commands.  
  • Logging & observability – logger names, redaction strategy, trace IDs, dashboards.  
  • Analytics/KPIs – event names, schema, when they fire.  
  • Testing frameworks & helpers (mention async helpers or fixtures unique to repo).
  
  ## Architecture
  • “Existing Components Leveraged” bullet list (files / classes).  
  • “New Components Introduced” bullet list (fully enumerated).  
  • Control-flow & data-flow diagram (ASCII or Mermaid).  
  • State-management, retry/fallback, and error-handling patterns (e.g., three-strike fallback).
  
  ## Completion Criteria & Metrics
  • Engineering metrics – latency, SLA, test coverage ≥ X %, lint/type-check clean, etc.  
  • Business metrics – conversion, NPS, error-rate < Y %, etc.  
  • Code-state definition of done – all CI jobs green, new DAG registered, talk-suite passes, docs updated.
  
  ## References
  • Exact repo paths examined – include line numbers or symbols when helpful.  
  • External URLs (one per line).  
  • Commit hashes or tags if specific revisions were read.
  
  ## Implementation Steps
  Break work into atomic tasks suitable for individual PRs.  
  Use the sub-template **verbatim** for every task:
  
  ### - [ ] Step <N>: <Concise Title>  
  **Description**: 1–2 sentences.  
  **Files**: list of files created/modified in this step.  
  **Reference(s)**: pointer(s) to rows in “## References”.  
  **Test(s)**: concrete test file names, fixtures/mocks, and the CI command that must pass.
  
  Granularity rules:  
  • One node/class/function per step unless trivial.  
  • No mixed concerns (e.g., “Implement X and refactor Y” must be two steps).  
  • Each step’s **Test(s)** must name at least one assertion or expected behaviour.
  
  ## Global Test Strategy
  • Unit, integration, e2e, load – what’s covered where.  
  • How to run locally (`make test`, `python -m pytest`, etc.).  
  • Env-vars / secrets layout (`.env.test`).  
  • Async helpers, fixtures, sandbox accounts.  
  • Coverage enforcement rule (PR fails if coverage < threshold).  
  
  ## Files to Modify / ## New Files to Create
  • Use Markdown tables or bullet lists.  
  • For **new files** provide:  
    – One-line purpose.  
    – Stub code block with signature(s).  
    – Required exports (`__all__`) or module wiring.  
    – Note if protobuf, OpenAPI, or YAML specs also added.
  
  GAP-FIX GUIDELINES (Always Apply)
  ────────────────────────────────
  1. ALWAYS describe how dependencies are added/pinned (e.g., `pyproject.toml`, `poetry.lock`).  
  2. If repo has custom test helpers (e.g., async graph helpers), reference & use them.  
  3. Call out existing services or models to be injected instead of rebuilt.  
  4. Explicitly enumerate **every** new component – no omissions.  
  5. Include retry/fallback/strike logic if part of the design pattern.  
  6. “Completion Criteria” must state both code-state and operational success metrics.  
  7. Each Implementation Step must have: references, granular scope, concrete tests.  
  8. Provide GitHub check-box list ready for copy-paste.  
  9. If conversational or persona suites are required, add a task for them.
  
  PRE-FLIGHT QUALITY GATE (Auto-check before you answer)
  ───────────────────────────────────────────────────────
  ✔ All top-level sections present and in correct order.  
  ✔ “Summary” ≤ 5 sentences and includes Problem + Success criteria.  
  ✔ “Technical Details” contains “External Dependencies” + dependency pinning method.  
  ✔ Architecture lists both Existing & New components.  
  ✔ Completion Criteria includes code-state AND operational metrics.  
  ✔ Implementation Steps use the exact sub-template and include tests.  
  ✔ Global Test Strategy explains commands and coverage enforcement.  
  ✔ New Files section provides stubs and export notes.  
  ✔ No placeholders, “TODO”, or speculative language.  
  ✔ All repo paths / URLs referenced are enumerated in “## References”.
  
  IF ANY ITEM IS MISSING, STOP, FIX, AND RE-EMIT THE ENTIRE PLAN.
  
  BEGIN OUTPUT
  ────────────
  Return only the GitHub-Markdown for the issue body, starting with “## Summary”.
  The workplan should be comprehensive enough that a developer or AI assistant could implement it without additional context, and structured in a way that makes it easy for an LLM to quickly understand and work with the contained information.
  IMPORTANT: Respond *only* with the Markdown content for the GitHub issue body. Do *not* wrap your entire response in a single Markdown code block (```). Start directly with the '## Summary' heading.
  """
  
          # Add the title as header prefix
          content_prefix = f"# {title}\n\n"
  
          # If not disable_search_grounding, use search grounding
          if not disable_search_grounding:
              prompt += (
                  "Search the internet for latest package versions and describe how to use them."
              )
  
          # Generate and update issue using the helper
          await _generate_and_update_issue(
              repo_path,
              llm_manager,
              model,
              prompt,
              issue_number,
              title,
              content_prefix,
              disable_search_grounding,
              debug,
              codebase_reasoning,
              _meta,
              ctx,
              github_command_func=github_command_func,
              git_command_func=git_command_func,
              reasoning_effort=reasoning_effort,
          )
  
      except Exception as e:
          detail = _format_exception_message(e)
          error_msg = (
              f"Error processing workplan: {detail}" if detail else "Error processing workplan"
          )
          if ctx:
              await ctx.log(level="error", message=error_msg)
  
          # Try to add error comment to issue
          try:
              error_comment = f"❌ **Error generating workplan**\n\n{detail if detail else str(e)}"
              await add_issue_comment(
                  repo_path, issue_number, error_comment, github_command_func=github_command_func
              )
          except Exception:
              # If we can't even add a comment, just log
              if ctx:
                  await ctx.log(
                      level="error", message=f"Failed to add error comment to issue: {str(e)}"
                  )