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]