ankorstore · ekkinox · May 8, 2025 · May 8, 2025
diff --git a/README.md b/README.md
@@ -78,6 +78,7 @@ Yokai provides ready to use `application templates` to start your projects:
 
 - for [gRPC applications](https://ankorstore.github.io/yokai/getting-started/grpc-application)
 - for [HTTP applications](https://ankorstore.github.io/yokai/getting-started/http-application)
+- for [MCP applications](https://ankorstore.github.io/yokai/getting-started/mcp-application)
 - for [worker applications](https://ankorstore.github.io/yokai/getting-started/worker-application)
 
 ## Showroom
@@ -86,6 +87,7 @@ Yokai provides a [showroom repository](https://github.com/ankorstore/yokai-showr
 
 - [gRPC demo application](https://github.com/ankorstore/yokai-showroom/tree/main/grpc-demo)
 - [HTTP demo application](https://github.com/ankorstore/yokai-showroom/tree/main/http-demo)
+- [MCP demo application](https://github.com/ankorstore/yokai-showroom/tree/main/mcp-demo)
 - [worker demo application](https://github.com/ankorstore/yokai-showroom/tree/main/worker-demo)
 
 ## Contributing

diff --git a/docs/demos/mcp-application.md b/docs/demos/mcp-application.md
@@ -0,0 +1,111 @@
+---
+title: Demos - MCP application
+icon: material/folder-eye-outline
+---
+
+# :material-folder-eye-outline: Demo - MCP application
+
+> Yokai's [showroom](https://github.com/ankorstore/yokai-showroom) provides an [MCP server demo application](https://github.com/ankorstore/yokai-showroom/tree/main/mcp-demo).
+
+## Overview
+
+This [MCP server demo application](https://github.com/ankorstore/yokai-showroom/tree/main/mcp-demo) is a simple [MCP server](https://modelcontextprotocol.io/introduction) to manage [gophers](https://go.dev/blog/gopher).
+
+It provides:
+
+- a [Yokai](https://github.com/ankorstore/yokai) application container, with the [MCP server](../modules/fxmcpserver.md) and [SQL](../modules/fxsql.md) modules to offer the gophers MCP server
+- a [MySQL](https://www.mysql.com/) container to store the gophers
+- a [MCP Inspector](https://modelcontextprotocol.io/docs/tools/inspector) container to interact with the MCP server
+- a [Jaeger](https://www.jaegertracing.io/) container to collect the application traces
+
+### Layout
+
+This demo application is following the [recommended project layout](https://go.dev/doc/modules/layout#server-project):
+
+- `cmd/`: entry points
+- `configs/`: configuration files
+- `db/`:
+	- `migrations/`: database migrations
+	- `seeds/`: database seeds
+- `internal/`:
+	- `domain/`: domain
+		- `model.go`: gophers model
+		- `repository.go`: gophers repository
+		- `service.go`: gophers service
+	- `mcp/`: MCP registrations
+		- `prompt/`: MCP prompts
+		- `resource/`: MCP resources
+		- `tool/`: MCP tools
+	- `bootstrap.go`: bootstrap
+	- `register.go`: dependencies registration
+
+### Makefile
+
+This demo application provides a `Makefile`:
+
+```
+make up      # start the docker compose stack
+make down    # stop the docker compose stack
+make logs    # stream the docker compose stack logs
+make fresh   # refresh the docker compose stack
+make migrate # run database migrations
+make test    # run tests
+make lint    # run linter
+```
+
+## Usage
+
+### Start the application
+
+To start the application, simply run:
+
+```shell
+make fresh
+```
+
+After a short moment, the application will offer:
+
+- [http://localhost:8080/sse](http://localhost:8080/sse): application MCP server (SSE)
+- [http://localhost:8081](http://localhost:8081): application core dashboard
+- [http://localhost:6274](http://localhost:6274): MCP inspector
+- [http://localhost:16686](http://localhost:16686): jaeger UI
+
+### Interact with the application
+
+#### MCP inspector
+
+You can use the provided [MCP Inspector](https://modelcontextprotocol.io/docs/tools/inspector), available on [http://localhost:6274](http://localhost:6274).
+
+To connect to the MCP server, use:
+
+- `SSE` as transport type
+- `http://mcp-demo-app:8080/sse` as URL
+
+Then simply click `Connect`: from there, you will be able to interact with the resources, prompts and tools of the application.
+
+#### MCP hosts
+
+If you use MCP compatible applications like [Cursor](https://www.cursor.com/), or [Claude desktop](https://claude.ai/download), you can register this application as MCP server:
+
+```json
+{
+  "mcpServers": {
+    "mcp-demo-app": {
+      "url": "http://localhost:8080/sse"
+    }
+  }
+}
+```
+
+Note, if you client does not support remote MCP servers, you can use a [local proxy](https://developers.cloudflare.com/agents/guides/test-remote-mcp-server/#connect-your-remote-mcp-server-to-claude-desktop-via-a-local-proxy):
+
+```json
+{
+  "mcpServers": {
+    "mcp-demo-app": {
+      "command": "npx",
+      "args": ["mcp-remote", "http://localhost:8080/sse"]
+    }
+  }
+}
+```
diff --git a/docs/getting-started/mcp-application.md b/docs/getting-started/mcp-application.md
@@ -0,0 +1,80 @@
+---
+title: Getting started - MCP application
+icon: material/rocket-launch-outline
+---
+
+# :material-rocket-launch-outline: Getting started - MCP application
+
+> Yokai provides a ready to use [MCP server application template](https://github.com/ankorstore/yokai-mcp-template) to start your MCP projects.
+
+## Overview
+
+The [MCP server application template](https://github.com/ankorstore/yokai-mcp-template)  provides:
+
+- a ready to extend [Yokai](https://github.com/ankorstore/yokai) application, with the [MCP server](../modules/fxmcpserver.md) module installed
+- a ready to use [dev environment](https://github.com/ankorstore/yokai-http-template/blob/main/docker-compose.yaml), based on [Air](https://github.com/air-verse/air) (for live reloading)
+- a ready to use [Dockerfile](https://github.com/ankorstore/yokai-http-template/blob/main/Dockerfile) for production
+- some examples of [MCP tool](https://github.com/ankorstore/yokai-mcp-template/blob/main/internal/tool/example.go) and [test](https://github.com/ankorstore/yokai-mcp-template/blob/main/internal/tool/example_test.go) to get started
+- 
+### Layout
+
+This template is following the [recommended project layout](https://go.dev/doc/modules/layout#server-project):
+
+- `cmd/`: entry points
+- `configs/`: configuration files
+- `internal/`:
+	- `tool/`: MCP tool and test examples
+	- `bootstrap.go`: bootstrap
+	- `register.go`: dependencies registration
+
+### Makefile
+
+This template provides a [Makefile](https://github.com/ankorstore/yokai-http-template/blob/main/Makefile):
+
+```
+make up      # start the docker compose stack
+make down    # stop the docker compose stack
+make logs    # stream the docker compose stack logs
+make fresh   # refresh the docker compose stack
+make test    # run tests
+make lint    # run linter
+```
+
+## Installation
+
+### With GitHub
+
+You can create your repository [using the GitHub template](https://github.com/new?template_name=yokai-mcp-template&template_owner=ankorstore).
+
+It will automatically rename your project resources, this operation can take a few minutes.
+
+Once ready, after cloning and going into your repository, simply run:
+
+```shell
+make fresh
+```
+
+### With gonew
+
+You can install [gonew](https://go.dev/blog/gonew), and simply run:
+
+```shell
+gonew github.com/ankorstore/yokai-mcp-template github.com/foo/bar
+cd bar
+make fresh
+```
+
+## Usage
+
+Once ready, the application will be available on:
+
+- [http://localhost:8080/sse](http://localhost:8080/sse) for the application MCP server
+- [http://localhost:8081](http://localhost:8081) for the application core dashboard
+
+## Going further
+
+To go further, you can:
+
+- check the [MCP server](../modules/fxmcpserver.md) module documentation to learn more about its features
+- follow the [HTTP application tutorial](../tutorials/http-application.md) to create, step by step, an HTTP application
+- test the [MCP demo application](../demos/mcp-application.md) to see all this in action
diff --git a/docs/index.md b/docs/index.md
@@ -64,4 +64,5 @@ Yokai provides ready to use `application templates` to start your projects:
 
 - for [gRPC applications](getting-started/grpc-application.md)
 - for [HTTP applications](getting-started/http-application.md)
+- for [MCP applications](getting-started/mcp-application.md)
 - for [worker applications](getting-started/worker-application.md)
diff --git a/docs/tutorials/grpc-application.md b/docs/tutorials/grpc-application.md
@@ -7,4 +7,4 @@ icon: material/school-outline
 
 > How to build, step by step, an gRPC application with Yokai.
 
-:material-sign-caution: Coming soon...
+:material-sign-caution: Coming soon, meanwhile you can check the [gRPC demo application](../demos/grpc-application.md).
diff --git a/docs/tutorials/mcp-application.md b/docs/tutorials/mcp-application.md
@@ -0,0 +1,10 @@
+---
+title: Tutorials - MCP application
+icon: material/school-outline
+---
+
+# :material-school-outline: Tutorial - MCP application
+
+> How to build, step by step, an MCP server application with Yokai.
+
+:material-sign-caution: Coming soon, meanwhile you can check the [MCP demo application](../demos/mcp-application.md).
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -72,14 +72,17 @@ nav:
   - "Getting started":
       - "gRPC application": getting-started/grpc-application.md
       - "HTTP application": getting-started/http-application.md
+      - "MCP application": getting-started/mcp-application.md
       - "Worker application": getting-started/worker-application.md
   - "Tutorials":
       - "gRPC application": tutorials/grpc-application.md
       - "HTTP application": tutorials/http-application.md
+      - "MCP application": tutorials/mcp-application.md
       - "Worker application": tutorials/worker-application.md
   - "Demos":
       - "gRPC application": demos/grpc-application.md
       - "HTTP application": demos/http-application.md
+      - "MCP application": demos/mcp-application.md
       - "Worker application": demos/worker-application.md
   - "Modules":
       - "Core": modules/fxcore.md
Original file line number	Diff line number	Diff line change
Expand Up		@@ -7,4 +7,4 @@ icon: material/school-outline

		> How to build, step by step, an gRPC application with Yokai.

		:material-sign-caution: Coming soon...
		:material-sign-caution: Coming soon, meanwhile you can check the [gRPC demo application](../demos/grpc-application.md).