From 227b704f58d7022af0dabf3354478f797904a0a9 Mon Sep 17 00:00:00 2001 From: Jonathan Vuillemin Date: Thu, 8 May 2025 10:21:38 +0200 Subject: [PATCH 1/2] doc(main): Updated documentation --- README.md | 2 + docs/demos/mcp-application.md | 111 ++++++++++++++++++++++++ docs/getting-started/mcp-application.md | 80 +++++++++++++++++ docs/index.md | 1 + docs/tutorials/grpc-application.md | 2 +- docs/tutorials/mcp-application.md | 10 +++ mkdocs.yml | 3 + 7 files changed, 208 insertions(+), 1 deletion(-) create mode 100644 docs/demos/mcp-application.md create mode 100644 docs/getting-started/mcp-application.md create mode 100644 docs/tutorials/mcp-application.md diff --git a/README.md b/README.md index 0ba8f33f..6a7ad0df 100644 --- 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 new file mode 100644 index 00000000..a27a6dd4 --- /dev/null +++ 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 new file mode 100644 index 00000000..c0cbdfa3 --- /dev/null +++ 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 index a64b160d..dc05ec92 100644 --- 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) \ No newline at end of file diff --git a/docs/tutorials/grpc-application.md b/docs/tutorials/grpc-application.md index 0785783c..fb355260 100644 --- 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... \ No newline at end of file +:material-sign-caution: Coming soon, meanwhile you can check the [gRPC demo application](../demos/grpc-application.md). \ No newline at end of file diff --git a/docs/tutorials/mcp-application.md b/docs/tutorials/mcp-application.md new file mode 100644 index 00000000..ad336fe6 --- /dev/null +++ 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). \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index 4068db7c..76bda253 100644 --- 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 From 35602596ee56a0159114ee7eee3283c02296d148 Mon Sep 17 00:00:00 2001 From: Jonathan Vuillemin Date: Thu, 8 May 2025 10:23:50 +0200 Subject: [PATCH 2/2] doc(main): Updated documentation --- docs/getting-started/mcp-application.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/getting-started/mcp-application.md b/docs/getting-started/mcp-application.md index c0cbdfa3..69f6501f 100644 --- a/docs/getting-started/mcp-application.md +++ b/docs/getting-started/mcp-application.md @@ -76,5 +76,5 @@ Once ready, the application will be available on: 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 +- follow the [MCP application tutorial](../tutorials/mcp-application.md) to create, step by step, an MCP server application - test the [MCP demo application](../demos/mcp-application.md) to see all this in action