MCP Iteration 1: stateless template inspection and preview

[patoperpetua]

Parent: #81

Goal

Prove that PostKit can expose a remote MCP interface from the existing Azure Function App without introducing a separate hosting service.

Scope

Add a stateless MCP endpoint, expected at /mcp, that delegates to existing/shared PostKit application services.

Initial tools:

• postkit.list_templates
• postkit.get_template
• postkit.get_template_schema
• postkit.validate_template
• postkit.preview_template

Explicitly exclude send_email from this iteration.

Architecture constraints

• MCP is an adapter, not a second implementation of PostKit logic.
• Extract/move reusable business logic out of Azure Function handlers where required so REST and MCP call the same services.
• Keep the endpoint stateless.
• Use the official MCP TypeScript SDK where practical.
• Preserve existing REST behavior.
• Do not introduce PostgreSQL, Redis, containers, or another service solely for MCP.

Authentication for this iteration

Use a simple Bearer API key mechanism sufficient for the PoC. The implementation should be replaceable by the shared auth layer in the next iteration.

Do not use Azure Function keys as the long-term PostKit authorization model.

Suggested structure

apps/
  api/
  mcp/              # or equivalent adapter within the Function app
packages/
  core/
  contracts/

Exact folder names should follow the repository's existing conventions.

Observability

Record enough structured information to debug calls without logging secrets or template recipient data unnecessarily:

• MCP method/tool
• request/correlation ID
• tenant where available
• success/failure
• duration

Acceptance criteria

• An MCP-compatible client can connect to the deployed PostKit endpoint.
• The client can discover the initial tool set.
• Template list/get/schema operations use existing PostKit template sources.
• Validation and preview results match the equivalent PostKit application behavior.
• Requests without valid PoC credentials are rejected.
• No email can be sent through MCP in this iteration.
• Existing REST endpoints continue to work.
• Automated tests cover tool input validation and representative tool calls.

Deliverables

• MCP server/adapter implementation.
• Azure Function route/hosting integration.
• Initial tool definitions and schemas.
• Basic PoC Bearer authentication.
• README/docs showing how an MCP client connects locally and to a deployed environment.