[pournasserian]

Closes #2504

What

The tool and resource conventions of F-MCP (#2423) that every capability epic builds its tools on (MCP-02, MCP-03, UX-03), with the first read-only tools for content types and change sets.

• Core (FluentCMS.Core.Tools):
  • [ExtensionPoint] IToolProvider and IResourceProvider, which built-ins and plugins implement alike (EXT-01, EXT-02).
  • AgentTool: a snake_case name, a title, a description written for a model, a JSON Schema for its input, a read-only flag and a handler. ToolCall passes the arguments and the call's own service scope.
  • ToolResult: the value as JSON, or the errors of a Result with an optional hint that names the call that finds a valid value.
  • ToolArgumentsReader: reports a missing, malformed or unknown argument by name, as FieldSettingsReader does for settings. ToolSchemas builds input schemas that describe every argument with an example and refuse others.
  • AgentResource: a fixed URI or a level 1 URI template, matched one path segment per parameter.
• Mcp: CoreToolsSetup puts every provider's tools and resources on the server on both transports. A name used twice stops the host at startup.
  • Tools carry the read-only annotation.
  • A success returns the JSON as structured content and as text.
  • A failure is a tool error (isError) with {"errors": [{"code", "message"}], "hint"}, never a protocol error.
• Built-in tools (FluentCMS.Core.Builtin.Tools):
  • list_content_types
  • get_content_type (slug, optional version)
  • get_schema_document (optional slug)
  • get_change_set (id)
  • get_change_set_diff (id)
• Built-in resources: fluentcms://schema and fluentcms://schema/{slug}, the schema documents from Add the schema document with field descriptions and examples #2473.
• CONTRIBUTING.md: the conventions under "Extension points".

Why

MCP-02 asks for descriptions, input schemas and errors written for an LLM, and MCP-03 for resources. F-EXT makes tool providers an extension point that lands with its first consumer. These read-only tools are that consumer, and the write tools follow on the same conventions.

Choices worth a look:

• Core owns the tool model, not the SDK. Core references no MCP package (ADR-0004). Mcp adapts each AgentTool to an SDK McpServerTool and each AgentResource to an McpServerResource, so a plugin's tool needs nothing from the transport.
• Arguments first: every tool reads its arguments before any service. A conformance test calls each tool with a service provider that throws, so a tool that skips the check fails. An unknown argument is an error rather than ignored, which catches an agent's typo.
• Errors carry a hint where one call finds the valid value. An unknown slug points to list_content_types, and an unknown version says to leave it out.
• Text and structured content carry the same JSON. Clients that read only text get everything. The text keeps quotes and apostrophes unescaped, because a model reads it, not a browser.
• ValidateOnStart builds the server options when the host starts, so a duplicate tool name fails there, not at the first call.
• The explicit tools capability is gone: the tool collection now always exists, so the SDK advertises it.
• Resources fail as protocol errors (ResourceNotFound), because a resource read has no error result. The message is the service's.
• Reads are not scoped yet: an agent with a key reads every type and set. Type, field and operation scopes belong to the credentials lane of F-MCP: MCP server, agent credentials, scopes and caps #2423.
• Not in this PR: write tools and session grouping (next slice), bulk operations and the MCP-01 coverage test, entry and entity tools (their lanes, on these conventions), and rule hints (F-RUL).

Tests

Unit:

• ToolProviderConformanceTests, derived for SchemaTools and ChangeSetTools:
  • unique snake_case names
  • a title and a description for every tool and resource
  • input schemas that are objects refusing other arguments, with a description on every argument and examples that pass an independent validator (NJsonSchema)
  • an unknown argument returns argument_unknown before any service is read
  • every resource URI has a scheme
• ToolArgumentsReader: values read, then missing, malformed and unknown arguments by name in order; no arguments, null, and a value that is not an object.
• ToolResult JSON with errors and hint. URI template matching and unescaping. Tool name rules.

Integration:

• Over HTTP on SQLite and PostgreSQL:
  • tools/list returns the five tools with descriptions, object schemas and the read-only annotation.
  • list_content_types and get_content_type return the current version and version 1.
  • get_schema_document returns the same JSON as ISchemaDocuments, for the site and for one type.
  • get_change_set and get_change_set_diff on a stored set show its state, initiator and operation, and the added field with its after value.
• An unknown slug, version and change set each return their service code, with a hint where there is one. A malformed and an unknown argument are reported together.
• Resources list the site document and the type template. Reading returns application/schema+json, and an unknown slug is refused with the service's message.
• Over stdio in-process on both providers, the tools answer the same way.
• A second provider with a built-in tool's name stops the web host at startup.
• The Add the MCP server host over streamable HTTP and stdio #2481 and Authenticate agents with their keys on both MCP transports #2487 tests now expect the built-in tools in the list.

The full suite ran locally against a postgres:17 container as well as SQLite, and markdownlint passes. No new package and no new project reference.

Checklist

• Linked to an issue a maintainer has confirmed
• Targets v2
• Tests or docs updated where behaviour changed
• No tool-generated co-author trailers or footers