Merge pull request #1 from ankorstore/main

Sync from fork

Author: adaosantos

.github/workflows/coverage.yml

@@ -32,6 +32,7 @@ jobs:
         - "sql"
         - "trace"
         - "worker"
+        - "fxclock"
         - "fxcore"
         - "fxconfig"
         - "fxcron"
@@ -41,6 +42,7 @@ jobs:
         - "fxhttpclient"
         - "fxhttpserver"
         - "fxlog"
+        - "fxmcpserver"
         - "fxmetrics"
         - "fxorm"
         - "fxsql"

.github/workflows/fxclock-ci.yml

@@ -0,0 +1,32 @@
+name: "fxclock-ci"
+
+on:
+    push:
+        branches:
+            - "feat**"
+            - "fix**"
+            - "hotfix**"
+            - "chore**"
+        paths:
+            - "fxclock/**.go"
+            - "fxclock/go.mod"
+            - "fxclock/go.sum"
+    pull_request:
+        types:
+            - opened
+            - synchronize
+            - reopened
+        branches:
+            - main
+        paths:
+            - "fxclock/**.go"
+            - "fxclock/go.mod"
+            - "fxclock/go.sum"
+
+jobs:
+    ci:
+        uses: ./.github/workflows/common-ci.yml
+        secrets: inherit
+        with:
+            module: "fxclock"
+            go_version: "1.21"

.github/workflows/fxmcpserver-ci.yml

@@ -0,0 +1,32 @@
+name: "fxmcpserver-ci"
+
+on:
+    push:
+        branches:
+            - "feat**"
+            - "fix**"
+            - "hotfix**"
+            - "chore**"
+        paths:
+            - "fxmcpserver/**.go"
+            - "fxmcpserver/go.mod"
+            - "fxmcpserver/go.sum"
+    pull_request:
+        types:
+            - opened
+            - synchronize
+            - reopened
+        branches:
+            - main
+        paths:
+            - "fxmcpserver/**.go"
+            - "fxmcpserver/go.mod"
+            - "fxmcpserver/go.sum"
+
+jobs:
+    ci:
+        uses: ./.github/workflows/common-ci.yml
+        secrets: inherit
+        with:
+            module: "fxmcpserver"
+            go_version: "1.23"

.release-please-manifest.json

@@ -1 +1 @@
-{"config":"1.5.0","log":"1.2.0","generate":"1.3.0","trace":"1.3.0","healthcheck":"1.1.0","httpclient":"1.4.0","httpserver":"1.6.0","orm":"1.1.0","fxconfig":"1.3.0","fxgenerate":"1.3.0","fxlog":"1.1.0","fxtrace":"1.2.0","fxmetrics":"1.2.0","fxhealthcheck":"1.1.0","fxorm":"1.2.0","fxhttpclient":"1.4.0","fxhttpserver":"1.7.0","fxcore":"1.10.0","worker":"1.2.0","fxworker":"1.1.0","fxcron":"1.1.0","grpcserver":"1.2.0","fxgrpcserver":"1.3.0","sql":"1.1.0","fxsql":"1.3.0","fxvalidator":"1.0.0"}
+{"config":"1.5.0","log":"1.2.0","generate":"1.3.0","trace":"1.4.0","healthcheck":"1.1.0","httpclient":"1.5.0","httpserver":"1.6.0","orm":"1.1.0","fxconfig":"1.3.0","fxgenerate":"1.3.0","fxlog":"1.1.0","fxtrace":"1.2.0","fxmetrics":"1.2.0","fxhealthcheck":"1.1.1","fxorm":"1.2.0","fxhttpclient":"1.4.0","fxhttpserver":"1.7.1","fxcore":"1.12.0","worker":"1.2.0","fxworker":"1.1.1","fxcron":"1.1.1","grpcserver":"1.2.0","fxgrpcserver":"1.3.1","sql":"1.1.0","fxsql":"1.3.0","fxvalidator":"1.0.0","fxclock":"1.0.0","fxmcpserver":"1.6.0"}

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

docs/assets/images/dash-tasks-dark.png

@@ -22,11 +22,12 @@ This demo application is following the [recommended project layout](https://go.d
 
 - `cmd/`: entry points
 - `configs/`: configuration files
-- `internal/`:
-  	- `interceptor/`: gRPC interceptors
-  	- `service/`: gRPC services
-  	- `bootstrap.go`: bootstrap
-  	- `register.go`: dependencies registration
+  - `internal/`:
+    - `api/`: gRPC API
+      - `interceptor/`: gRPC interceptors
+      - `service/`: gRPC services
+    - `bootstrap.go`: bootstrap
+    - `register.go`: dependencies registration
 - `proto/`: protobuf definition and stubs
 
 ### Makefile
@@ -76,7 +77,7 @@ This demo application also provides [reflection](../modules/fxgrpcserver.md#refl
 
 ### Authentication
 
-This demo application provides example [authentication interceptors](https://github.com/ankorstore/yokai-showroom/tree/main/grpc-demo/internal/interceptor/authentication.go).
+This demo application provides example [authentication interceptors](https://github.com/ankorstore/yokai-showroom/tree/main/grpc-demo/internal/api/interceptor/authentication.go).
 
 You can enable authentication in the application [configuration file](https://github.com/ankorstore/yokai-showroom/tree/main/grpc-demo/configs/config.yaml) with `config.authentication.enabled=true`.
 

docs/assets/images/dash-tasks-light.png

@@ -27,11 +27,13 @@ This demo application is following the [recommended project layout](https://go.d
 	- `migrations/`: database migrations
 	- `seeds/`: database seeds
 - `internal/`:
-	- `handler/`: HTTP handlers
-	- `middleware/`: HTTP middlewares
-	- `model/`: models
-	- `repository/`: models repositories
-	- `service/`: services
+	- `api/`: HTTP API
+		- `handler/`: HTTP handlers
+		- `middleware/`: HTTP middlewares
+	- `domain/`: domain
+		- `model.go`: gophers model
+		- `repository.go`: gophers repository
+		- `service.go`: gophers service
 	- `bootstrap.go`: bootstrap
 	- `register.go`: dependencies registration
 	- `router.go`: routing registration
@@ -81,7 +83,7 @@ On [http://localhost:8080](http://localhost:8080), you can use:
 
 ### Authentication
 
-This demo application provides an example [authentication middleware](https://github.com/ankorstore/yokai-showroom/blob/main/http-demo/internal/middleware/authentication.go).
+This demo application provides an example [authentication middleware](https://github.com/ankorstore/yokai-showroom/blob/main/http-demo/internal/api/middleware/authentication.go).
 
 You can enable authentication in the application [configuration file](https://github.com/ankorstore/yokai-showroom/blob/main/http-demo/configs/config.yaml) with `config.authentication.enabled=true`.
 

docs/demos/grpc-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/mcp](http://localhost:8080/mcp): application MCP server (Streamable HTTP)
+- [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:
+
+- `Streamable HTTP` as transport type
+- `http://mcp-demo-app:8080/mcp` 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/mcp"
+    }
+  }
+}
+```
+
+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/mcp"]
+    }
+  }
+}
+```