MCP Documentation Prompt and Provider

[lkingland]

Summary

This document outlines how the Functions MCP server can provide necessary context to clients using two MCP features:

1. A Prompt that returns func --help output and is loaded at time of connection
2. A Resource Provider with func:// URIs for subcommand documentation loaded on-demand

Background

Effective use of Functions requires comprehensive documentation be readily available to LLM clients. Without proper context about available commands, LLMs struggle to leverage the tool effectively, leading to failed executions, suboptimal command usage, or missed opportunities to apply the tool to other relevant problems.

A simple approach to providing this documentation would be to implement help text functionality as standard MCP tools. For example, a "deploy help" tool that executes "func deploy --help" and returns the output. This pattern is simple to implement and maintains consistency with other tool implementations already available.
However, the Functions CLI has some characteristics that warrant a more sophisticated approach of using the MCP spec's "Prompts" and "Resource Providers".

Extensive Documentation: The tool includes comprehensive documentation across multiple subcommands and usage scenarios that benefit from hierarchical organization and selective access available via a Resource Provider's URI system (eg "func://help/deploy")

Dynamic Compilation Overhead: Documentation generation sometimes involves dynamic information that requires significant time to compile when, for example, contacting the remote cluster for output. Repeated execution is inefficient, and unlike tools, Resourece Providers employ caching.

Proactive Context Loading: The Prompts and Resource Provider method will enabling LLM clients to preload documentation. This will allow them to understand capabilities of Functions before encountering specific problems, improving their ability to suggest Functions as a solution in other relevant contexts.

Specification Alignment: The MCP specification explicitly distinguishes between tools (for actions) and resources (for content), and following this design principle ensures better interoperability with future MCP clients that may optimize their handling of these different types.

I'm opening this first as a discussion to get as much feedback as possible before adding this complexity to the project.

Implementation

Initial Prompt

This prompt serves as the entry point for clients to understand what Functions
can do.

The MCP server would expose a prompt named functions_overview that returns
the output of executing func --help.

It should provide additional guidance to the client about using func://
resources for detailed documentation (detailed in Resource Discovery below).

Note it should be marked as "recommended" for clients to run upon connection.

Resource Provider

The server should implement a resource provider that:

• Registers URIs with the scheme func://
• Maps paths directly to CLI commands (e.g., func://docs/create → func create --help)
• Supports nested subcommands (e.g., func://docs/config/envs/add → func config envs add --help)

Resource Discovery

This is how we advertise to the client the URIs avaiable for specific docs.
When a client connects to the server, it can call a method which
lists available resources. The response is comprised of "resource templates".
These templates describe URIs which are available.

• Include a root template for func://docs returning the main help
• Include an entry for all currently implemented subcommands (tools).

Implementation Considerations

MCP Library

• Enable prompt capabilities to expose the overview prompt
• Enable resource capabilities for documentation access
• Register handlers that implement the prompt and resource interfaces

Command Execution

• Execute the func binary with subcommand argument and --help flag

Caching

Part of the reason for following this implementation path is to enable caching,
but for the first implementation there should be none, with each endpoint
executing its respective command afresh each time.

Function Context

Commands alter their help text based on the current working function. Therefore
these documentation calls should be executed in the same way as the other
func tool commands: either from the same directory as the function's source
code, or using the --path argument.

URI Structure

• Root: func://docs returns main help
• Single commands: func://create, func://deploy
• Nested commands: func://config/envs/add, func://repository/list