Smithy MCP Extensions

@innFactory/smithy-mcp is a lightweight, open-source library that provides a set of Smithy traits to annotate API operations for the Model Context Protocol (MCP).

It allows you to seamlessly enrich your Smithy API definitions with metadata, making them discoverable and usable as "tools" by MCP agents, AI models, or other automated systems.

The core design philosophy is Convention over Configuration: get started with a single trait and only add more detail when you need to override the sensible defaults.

Features

• Minimal Overhead: Expose an operation as an MCP tool with a single @mcpTool trait.
• Convention over Configuration: The system automatically infers names and descriptions from your existing model. You only need to add annotations when you want to override these defaults.
• Rich Metadata: Optionally add detailed descriptions, categories, versions, parameter examples, and full end-to-end usage examples.
• Clear Naming: All traits are prefixed with mcp for clarity and to avoid conflicts.
• Type-Safe: By defining metadata within the Smithy IDL, you get compile-time validation for your tool definitions.

Installation

To use these traits in your Smithy project, you need to add this repository as a dependency. In your smithy-build.json, add the following to the maven dependencies section.

(Note: The exact coordinates will be available once the package is published to a Maven repository. For now, you can vendor the model files directly.)

A typical setup for importing a Git repository as a dependency would look like this (example using smithy-cli):

{
  "version": "1.0.0",
  "sources": ["model"],
  "maven": {
    "dependencies": [
      // Dependency will be added here once published
    ]
  }
}

For now, you can add the model/ directory from this repository to your project's Smithy source path.

How to Use

1. Import the Traits

In your .smithy file, import the traits you want to use from the de.innfactory.mcp namespace.

$version: "2.0"

namespace com.example.api

use de.innfactory.mcp#mcpTool
use de.innfactory.mcp#mcpName
use de.innfactory.mcp#mcpDescription
use de.innfactory.mcp#mcpCategories
use de.innfactory.mcp#mcpParameter
use de.innfactory.mcp#mcpExamples

2. Annotate Your Operations

Minimal Example (Convention-based)

To expose an operation as a tool, simply add the @mcpTool trait. The tool's name will be derived from the operation name (GetUser), and its description will be taken from the standard @documentation trait.

/// This documentation will be used as the default tool description.
@mcpTool
@http(method: "GET", uri: "/users/{id}")
operation GetUser { /* ... */ }

Full Example (Configuration-based)

For more control, you can use the other mcp* traits to provide explicit metadata.

/// This is the fallback documentation.
@mcpTool
@mcpName("GetUserProfile") // Override the default name "GetUser"
@mcpDescription("Retrieves the full public profile for a user by their ID.")
@mcpCategories(["User Management", "Data Retrieval"])
@mcpVersion("1.1.0")
@mcpExamples([
  {
    title: "Retrieve a standard user",
    input: {
      userId: "usr_12345"
    },
    output: {
      body: {
        id: "usr_12345",
        name: "Jane Doe",
        email: "jane.doe@example.com"
      }
    }
  }
])
@http(method: "GET", uri: "/users/{userId}")
operation GetUser {
  input := {
    @required
    @httpLabel
    /// Default documentation for the parameter.
    @mcpParameter(
      example: "usr_12345" // Provide a concrete example value
    )
    userId: String
  },
  output := { /* ... */ }
}

Available Traits

Trait	Target	Description
@mcpTool	operation	(Required) Marker trait to expose the operation as an MCP tool.
@mcpName	operation	Overrides the default tool name.
@mcpDescription	operation	Overrides the default description (which is inferred from @documentation).
@mcpCategories	operation	A list of strings to categorize the tool.
@mcpVersion	operation	A semantic version string for the tool.
@mcpParameter	member	Provides an example value for an input parameter. The description is inferred from @documentation.
@mcpExamples	operation	A list of end-to-end (title, input, output) examples for the tool.

Contributing

Contributions are welcome! Please feel free to open an issue or submit a pull request.

License

This project is licensed under the MIT License. See the LICENSE file for details.