Skip to content
Clean Model Context Protocol
Lean Mean Clean Apps

Five templates, one brand, one search box. Everything in the docs is in here, including the bits we hoped you'd skim.

Try one of these

Results say which template they came from, so you won't end up reading about Lambda when you wanted GraphQL. Again.

Tools

Every tool lives in src/Presentation/Tools, one static class per feature. Arguments are JSON, named in camelCase. Every tool returns its result twice: as a text content block holding JSON, for models that read, and as structuredContent, for clients that parse, with an output schema in the tool’s listing. After the text comes a resource_link block for each movie, author or review in the result, pointing at its movies://, authors:// or reviews:// resource, so a client can open it. In a solution created with --include-auth, every tool needs a token.

Tool Title Read-only Destructive Idempotent
movies_search Search movies yes yes
movies_get Get movie yes yes
authors_search Search authors yes yes
reviews_list List reviews yes yes
reviews_write Write review yes
reviews_delete Delete review yes yes

Every tool has openWorldHint false: they only ever touch this server’s own database. Every tool also has an icon, a movie, an author or a review, from the brand repository.

Finds movies whose title contains a search term, ignoring case, in title order. Leave the query empty to browse every movie a page at a time.

Argument Type Default Rules
query string none Up to 100 characters
offset integer 0 0 or more
limit integer 10 1 to 50
includeReviews boolean false Also return every review of each movie

Returns a page of movies.

{
"items": [
{ "id": "cb188ef6-14e7-f85f-2f78-924c2ab26b28", "title": "Deep Space Gardeners", "reviewCount": 5, "averageStars": 3.4, "reviews": null },
{ "id": "dfefa450-5454-6a4d-a4aa-95a9b047c17b", "title": "Postcards from Outer Space", "reviewCount": 1, "averageStars": 3, "reviews": null }
],
"totalCount": 4,
"nextOffset": 2
}

Gets one movie with its review count, average stars and every review, including each author’s name.

Argument Type Rules
movieId guid An existing movie

Returns a movie with reviews filled in.

Finds authors by first name, last name or full name, ignoring case, in last-name order. Leave the query empty to browse every author a page at a time.

Argument Type Default Rules
query string none Up to 100 characters
offset integer 0 0 or more
limit integer 10 1 to 50
includeReviews boolean false Also return every review each author has written

Returns a page of authors.

Lists reviews with their star rating and the title and author of each, in movie-title order. Filter by movie, by author, by words in the review or by a minimum star rating, or pass a reviewId to get one review.

Argument Type Default Rules
movieId guid none Only reviews of this movie
authorId guid none Only reviews by this author
reviewId guid none Get this one review instead. The other filters are ignored
query string none Only reviews whose text contains it, ignoring case. Up to 100 characters
minStars integer none Only reviews with at least this many stars, from 1 to 5
offset integer 0 0 or more
limit integer 10 1 to 50

Returns a page of reviews.

Creates a review of a movie by an author, with optional text, or changes the stars and text of an existing review when reviewId is passed. A review’s movie and author can’t change.

Argument Type Rules
stars integer 1 to 5
movieId guid Needed to create a review. An existing movie
authorId guid Needed to create a review. An existing author
reviewId guid Leave empty to create. An existing review to change
text string Optional. Up to 1000 characters. Leave it empty when changing a review to keep its text

Returns the saved review.

Permanently deletes a review. The description tells the model to confirm with the user first, and the destructiveHint tells the client the same.

Argument Type Rules
reviewId guid An existing review

Returns { "reviewId": "...", "deleted": true }.

Properties with no value are written as null, not left out, so every result matches its output schema. The schema describes them with anyOf and a null type, which clients that only understand one type per property accept too.

Every search and list tool returns one page.

Property Type Description
items array The results on this page
totalCount integer The number of results across every page
nextOffset integer Pass it as offset to get the next page. Null on the last page
Property Type Description
id guid The movie’s id
title string The movie’s title
reviewCount integer How many reviews the movie has
averageStars number The average rating to one decimal place. Null when there are no reviews
reviews array of review Every review of the movie. Null unless asked for
Property Type Description
id guid The author’s id
name string The author’s full name
reviewCount integer How many reviews the author has written
averageStars number The average rating they give. Null when there are no reviews
reviews array of review Every review by the author. Null unless asked for
Property Type Description
id guid The review’s id
stars integer The rating, from 1 to 5
movieId guid The movie’s id
movieTitle string The movie’s title
authorId guid The author’s id
authorName string The author’s full name
text string What the author said about the movie, or null when there’s no text

A failed tool call is a result with isError true and one text block, so the model can read what went wrong and try again. The protocol itself never errors for these.

Starts with When
Validation Failed: An argument breaks one of the rules above. Lists every rule it broke, then says to correct the arguments and call again
Not Found: The movie, author or review doesn’t exist. Says which, then which tools return valid ids
Error: Something unexpected happened
{
"isError": true,
"content": [
{ "type": "text", "text": "Validation Failed: Stars: A star rating must be between 1 and 5. Correct the arguments and call the tool again." }
]
}