mcp: add describe tool for Function inspection

[thonmay]

Changes

Adds a new MCP tool describe that exposes the func describe command to agents, completing the core Function lifecycle toolset alongside create, build, deploy, list, and delete.

Tool behavior:

• Accepts optional name (positional arg) or --path flag — mutually exclusive
• When neither is provided, describes the Function in the current working directory
• Supports --namespace, --output, and --verbose flags
• Read-only: ReadOnlyHint: true, IdempotentHint: true, no readonly guard needed

Tests added (5):

• TestTool_Describe_Args — name-based lookup with all flags
• TestTool_Describe_PathBased — path-based lookup
• TestTool_Describe_MutualExclusion — both path and name provided returns error
• TestTool_Describe_NeitherProvided — no args describes function in cwd
• TestTool_Describe_BinaryFailure — executor error propagated correctly

/kind enhancement

Fixes #3729

Add MCP `describe` tool for inspecting deployed Functions

[knative-prow]

@thonmay: The label(s) kind/feature cannot be applied, because the repository doesn't have them.

Details

In response to this:

Changes

Adds a new MCP tool describe that exposes the func describe command to agents, completing the core Function lifecycle toolset alongside create, build, deploy, list, and delete.

Tool behavior:

• Accepts optional name (positional arg) or --path flag — mutually exclusive
• When neither is provided, describes the Function in the current working directory
• Supports --namespace, --output, and --verbose flags
• Read-only: ReadOnlyHint: true, IdempotentHint: true, no readonly guard needed

Tests added (5):

• TestTool_Describe_Args — name-based lookup with all flags
• TestTool_Describe_PathBased — path-based lookup
• TestTool_Describe_MutualExclusion — both path and name provided returns error
• TestTool_Describe_NeitherProvided — no args describes function in cwd
• TestTool_Describe_BinaryFailure — executor error propagated correctly

/kind feature

Fixes #3729

Add MCP `describe` tool for inspecting deployed Functions

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.

[linux-foundation-easycla]

The committers listed above are authorized under a signed CLA.

• ✅ login: thonmay / name: Thonmay (704b5f5)

[knative-prow]

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by: thonmay
Once this PR has been reviewed and has the lgtm label, please assign jrangelramos for approval. For more information see the Code Review Process.

The full list of commands accepted by this bot can be found here.

Details

Needs approval from an approver in each of these files:

• OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[knative-prow]

Welcome @thonmay! It looks like this is your first PR to knative/func 🎉

[knative-prow]

Hi @thonmay. Thanks for your PR.

I'm waiting for a knative member to verify that this patch is reasonable to test. If it is, they should reply with /ok-to-test on its own line. Until that is done, I will not automatically test new commits in this PR, but the usual testing commands by org members will still work.

Regular contributors should join the org to skip this step.

Once the patch is verified, the new status will be reflected by the ok-to-test label.

I understand the commands that are listed here.

Details

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.

[thonmay]

/kind enhancement

[gauron99]

🦴 CAVEMAN REVIEWER HAVE QUESTIONS 🦴

Thank for contribution. Before review, answer these. No answer, no review.

1. Explain

• In your own words — what this change do and how it work? Not copy from issue, not copy from PR template. YOUR words.
• Walk caveman through what happen when agent call this tool. Where request go? What touch what?

2. Why

• What specific problem this solve? What agent NOT do today without this?
• Give concrete example — real scenario where agent stuck without describe.
• How this different from list? When agent use one vs other?

3. Testing

• You run this through MCP server locally? Not CI — you, on your machine.
• Do you screenshot your work? Caveman like see proof it work.

4. Understanding

• Explain in own words how surrounding MCP code work and why structured that way.
• What break if we no merge this?

We welcome all contributors. But change must be understood by author and solve real problem. PRs that no demonstrate this — closed.

[thonmay]

1. Explain

Wraps func describe as MCP tool. Agent calls it → handler validates path and name aren't both set (mutually exclusive) → builds CLI args → executor runs func describe [name] --namespace X --output Y → returns output as MCP text response.

Same pattern as every other tool in the package. Nothing fancy.

2. Why

Agent deploys a Function. Wants to check: is the route serving? What revision is active? What image is running?

• list gives a table of ALL functions. Name, runtime, URL, ready. That's it. Directory listing.
• func://function reads local func.yaml. Local config, not live cluster state.

Neither tells you revisions, conditions, subscriptions, or image digest for a specific Function. Without describe, agent has to shell out to kubectl. Breaks the MCP workflow.

list = "what exists?" / describe = "tell me about THIS one"

3. Testing

Built binary, ran MCP server, sent JSON-RPC over stdio:

• tools/list → describe shows up, readOnlyHint: true
• tools/call describe(name="hello", namespace="default") → executes, hits "no k8s cluster" error (expected, no cluster locally)
• All 42 unit tests pass

Screenshots attached. No cluster available for full e2e, but the chain works end-to-end up to the cluster boundary.

4. Understanding

Server wraps Go MCP SDK. Each tool = *mcp.Tool var + handler on *Server. Handler validates → checks s.readonly if mutating → calls s.executor.Execute() → returns output. Executor interface lets tests mock the CLI. defaultExecutor runs exec.CommandContext.

No merge = agents can deploy but can't inspect. Gap in the lifecycle.

[thonmay]

[lkingland]

/ok-to-test

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 57.03%. Comparing base (e435a89) to head (704b5f5).
⚠️ Report is 20 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #3736      +/-   ##
==========================================
+ Coverage   56.95%   57.03%   +0.07%     
==========================================
  Files         181      182       +1     
  Lines       21116    21145      +29     
==========================================
+ Hits        12026    12059      +33     
+ Misses       7866     7862       -4     
  Partials     1224     1224              

Flag	Coverage Δ
e2e	35.76% <0.00%> (-0.06%)	⬇️
e2e go	32.38% <0.00%> (-0.05%)	⬇️
e2e node	28.16% <0.00%> (-0.05%)	⬇️
e2e python	32.75% <0.00%> (-0.05%)	⬇️
e2e quarkus	28.28% <0.00%> (-0.07%)	⬇️
e2e rust	27.71% <0.00%> (?)
e2e springboot	26.22% <0.00%> (-0.04%)	⬇️
e2e typescript	28.26% <0.00%> (-0.07%)	⬇️
e2e-config-ci	17.67% <0.00%> (-0.03%)	⬇️
integration	17.27% <0.00%> (-0.03%)	⬇️
unit macos-14	45.12% <100.00%> (+0.07%)	⬆️
unit macos-latest	45.12% <100.00%> (+0.07%)	⬆️
unit ubuntu-24.04-arm	45.39% <100.00%> (+0.07%)	⬆️
unit ubuntu-latest	46.08% <100.00%> (+0.07%)	⬆️
unit windows-latest	45.17% <100.00%> (+0.07%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.