Skip to content

Commit e126b4f

Browse files
ekkinoxekkinox
authored
doc(main): Updated documentation (#344)
1 parent 77157ca commit e126b4f

File tree

7 files changed

+208
-1
lines changed

7 files changed

+208
-1
lines changed

‎README.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -78,6 +78,7 @@ Yokai provides ready to use `application templates` to start your projects:
7878

7979
- for [gRPC applications](https://ankorstore.github.io/yokai/getting-started/grpc-application)
8080
- for [HTTP applications](https://ankorstore.github.io/yokai/getting-started/http-application)
81+
- for [MCP applications](https://ankorstore.github.io/yokai/getting-started/mcp-application)
8182
- for [worker applications](https://ankorstore.github.io/yokai/getting-started/worker-application)
8283

8384
## Showroom
@@ -86,6 +87,7 @@ Yokai provides a [showroom repository](https://github.com/ankorstore/yokai-showr
8687

8788
- [gRPC demo application](https://github.com/ankorstore/yokai-showroom/tree/main/grpc-demo)
8889
- [HTTP demo application](https://github.com/ankorstore/yokai-showroom/tree/main/http-demo)
90+
- [MCP demo application](https://github.com/ankorstore/yokai-showroom/tree/main/mcp-demo)
8991
- [worker demo application](https://github.com/ankorstore/yokai-showroom/tree/main/worker-demo)
9092

9193
## Contributing

‎docs/demos/mcp-application.md‎

Lines changed: 111 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,111 @@
1+
---
2+
title: Demos - MCP application
3+
icon: material/folder-eye-outline
4+
---
5+
6+
# :material-folder-eye-outline: Demo - MCP application
7+
8+
> 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).
9+
10+
## Overview
11+
12+
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).
13+
14+
It provides:
15+
16+
- 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
17+
- a [MySQL](https://www.mysql.com/) container to store the gophers
18+
- a [MCP Inspector](https://modelcontextprotocol.io/docs/tools/inspector) container to interact with the MCP server
19+
- a [Jaeger](https://www.jaegertracing.io/) container to collect the application traces
20+
21+
### Layout
22+
23+
This demo application is following the [recommended project layout](https://go.dev/doc/modules/layout#server-project):
24+
25+
- `cmd/`: entry points
26+
- `configs/`: configuration files
27+
- `db/`:
28+
- `migrations/`: database migrations
29+
- `seeds/`: database seeds
30+
- `internal/`:
31+
- `domain/`: domain
32+
- `model.go`: gophers model
33+
- `repository.go`: gophers repository
34+
- `service.go`: gophers service
35+
- `mcp/`: MCP registrations
36+
- `prompt/`: MCP prompts
37+
- `resource/`: MCP resources
38+
- `tool/`: MCP tools
39+
- `bootstrap.go`: bootstrap
40+
- `register.go`: dependencies registration
41+
42+
### Makefile
43+
44+
This demo application provides a `Makefile`:
45+
46+
```
47+
make up # start the docker compose stack
48+
make down # stop the docker compose stack
49+
make logs # stream the docker compose stack logs
50+
make fresh # refresh the docker compose stack
51+
make migrate # run database migrations
52+
make test # run tests
53+
make lint # run linter
54+
```
55+
56+
## Usage
57+
58+
### Start the application
59+
60+
To start the application, simply run:
61+
62+
```shell
63+
make fresh
64+
```
65+
66+
After a short moment, the application will offer:
67+
68+
- [http://localhost:8080/sse](http://localhost:8080/sse): application MCP server (SSE)
69+
- [http://localhost:8081](http://localhost:8081): application core dashboard
70+
- [http://localhost:6274](http://localhost:6274): MCP inspector
71+
- [http://localhost:16686](http://localhost:16686): jaeger UI
72+
73+
### Interact with the application
74+
75+
#### MCP inspector
76+
77+
You can use the provided [MCP Inspector](https://modelcontextprotocol.io/docs/tools/inspector), available on [http://localhost:6274](http://localhost:6274).
78+
79+
To connect to the MCP server, use:
80+
81+
- `SSE` as transport type
82+
- `http://mcp-demo-app:8080/sse` as URL
83+
84+
Then simply click `Connect`: from there, you will be able to interact with the resources, prompts and tools of the application.
85+
86+
#### MCP hosts
87+
88+
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:
89+
90+
```json
91+
{
92+
"mcpServers": {
93+
"mcp-demo-app": {
94+
"url": "http://localhost:8080/sse"
95+
}
96+
}
97+
}
98+
```
99+
100+
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):
101+
102+
```json
103+
{
104+
"mcpServers": {
105+
"mcp-demo-app": {
106+
"command": "npx",
107+
"args": ["mcp-remote", "http://localhost:8080/sse"]
108+
}
109+
}
110+
}
111+
```

‎docs/getting-started/mcp-application.md‎

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
---
2+
title: Getting started - MCP application
3+
icon: material/rocket-launch-outline
4+
---
5+
6+
# :material-rocket-launch-outline: Getting started - MCP application
7+
8+
> Yokai provides a ready to use [MCP server application template](https://github.com/ankorstore/yokai-mcp-template) to start your MCP projects.
9+
10+
## Overview
11+
12+
The [MCP server application template](https://github.com/ankorstore/yokai-mcp-template) provides:
13+
14+
- a ready to extend [Yokai](https://github.com/ankorstore/yokai) application, with the [MCP server](../modules/fxmcpserver.md) module installed
15+
- 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)
16+
- a ready to use [Dockerfile](https://github.com/ankorstore/yokai-http-template/blob/main/Dockerfile) for production
17+
- 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
18+
-
19+
### Layout
20+
21+
This template is following the [recommended project layout](https://go.dev/doc/modules/layout#server-project):
22+
23+
- `cmd/`: entry points
24+
- `configs/`: configuration files
25+
- `internal/`:
26+
- `tool/`: MCP tool and test examples
27+
- `bootstrap.go`: bootstrap
28+
- `register.go`: dependencies registration
29+
30+
### Makefile
31+
32+
This template provides a [Makefile](https://github.com/ankorstore/yokai-http-template/blob/main/Makefile):
33+
34+
```
35+
make up # start the docker compose stack
36+
make down # stop the docker compose stack
37+
make logs # stream the docker compose stack logs
38+
make fresh # refresh the docker compose stack
39+
make test # run tests
40+
make lint # run linter
41+
```
42+
43+
## Installation
44+
45+
### With GitHub
46+
47+
You can create your repository [using the GitHub template](https://github.com/new?template_name=yokai-mcp-template&template_owner=ankorstore).
48+
49+
It will automatically rename your project resources, this operation can take a few minutes.
50+
51+
Once ready, after cloning and going into your repository, simply run:
52+
53+
```shell
54+
make fresh
55+
```
56+
57+
### With gonew
58+
59+
You can install [gonew](https://go.dev/blog/gonew), and simply run:
60+
61+
```shell
62+
gonew github.com/ankorstore/yokai-mcp-template github.com/foo/bar
63+
cd bar
64+
make fresh
65+
```
66+
67+
## Usage
68+
69+
Once ready, the application will be available on:
70+
71+
- [http://localhost:8080/sse](http://localhost:8080/sse) for the application MCP server
72+
- [http://localhost:8081](http://localhost:8081) for the application core dashboard
73+
74+
## Going further
75+
76+
To go further, you can:
77+
78+
- check the [MCP server](../modules/fxmcpserver.md) module documentation to learn more about its features
79+
- follow the [HTTP application tutorial](../tutorials/http-application.md) to create, step by step, an HTTP application
80+
- test the [MCP demo application](../demos/mcp-application.md) to see all this in action

‎docs/index.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -64,4 +64,5 @@ Yokai provides ready to use `application templates` to start your projects:
6464

6565
- for [gRPC applications](getting-started/grpc-application.md)
6666
- for [HTTP applications](getting-started/http-application.md)
67+
- for [MCP applications](getting-started/mcp-application.md)
6768
- for [worker applications](getting-started/worker-application.md)

‎docs/tutorials/grpc-application.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,4 +7,4 @@ icon: material/school-outline
77

88
> How to build, step by step, an gRPC application with Yokai.
99
10-
:material-sign-caution: Coming soon...
10+
:material-sign-caution: Coming soon, meanwhile you can check the [gRPC demo application](../demos/grpc-application.md).

‎docs/tutorials/mcp-application.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
---
2+
title: Tutorials - MCP application
3+
icon: material/school-outline
4+
---
5+
6+
# :material-school-outline: Tutorial - MCP application
7+
8+
> How to build, step by step, an MCP server application with Yokai.
9+
10+
:material-sign-caution: Coming soon, meanwhile you can check the [MCP demo application](../demos/mcp-application.md).

‎mkdocs.yml‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -72,14 +72,17 @@ nav:
7272
- "Getting started":
7373
- "gRPC application": getting-started/grpc-application.md
7474
- "HTTP application": getting-started/http-application.md
75+
- "MCP application": getting-started/mcp-application.md
7576
- "Worker application": getting-started/worker-application.md
7677
- "Tutorials":
7778
- "gRPC application": tutorials/grpc-application.md
7879
- "HTTP application": tutorials/http-application.md
80+
- "MCP application": tutorials/mcp-application.md
7981
- "Worker application": tutorials/worker-application.md
8082
- "Demos":
8183
- "gRPC application": demos/grpc-application.md
8284
- "HTTP application": demos/http-application.md
85+
- "MCP application": demos/mcp-application.md
8386
- "Worker application": demos/worker-application.md
8487
- "Modules":
8588
- "Core": modules/fxcore.md

0 commit comments

Comments
 (0)