Bjjcoach MCP Server

BJJ教练MCP服务器

模型上下文协议（MCP）服务器，为AI助手提供对BJJ（巴西柔术）位置和视频数据的访问。这是一个公共骨架存储库，旨在用作私人BJJ Coach应用程序中的库。

概述

此MCP服务器向AI助手提供了三种工具：

• 搜索位置 -按姓名搜索BJJ职位
• get_position_元数据 -获取职位的详细信息
• search_videos_for_position -查找某个职位的教学视频

骨架使用 模拟提供者 返回样本数据，使其对公共存储库安全。您的私有应用程序应该实现可以访问您实际数据的真实提供者。

建筑

关注点分离

该项目将公共MCP服务器接口与私有数据实现清晰地分开：

Public Skeleton (this repo)
├── Behaviours (contracts)
│   ├── BJJCoachMCP.PositionProvider
│   └── BJJCoachMCP.VideoProvider
├── Mock Providers (sample data)
│   ├── BJJCoachMCP.MockPositionProvider
│   └── BJJCoachMCP.MockVideoProvider
└── MCP Server (protocol implementation)
    └── BJJCoachMCP.Server

Private Application (your repo)
└── Real Providers (your data)
    ├── YourApp.PositionProvider (implements BJJCoachMCP.PositionProvider)
    └── YourApp.VideoProvider (implements BJJCoachMCP.VideoProvider)

运作原理

1. 行为 定义供应商必须执行的合同
2. 模拟提供者 默认配置（对公共仓库安全）
3. 您的私人应用 重写配置以使用真实提供者
4. MCP服务器 调用配置的任何提供者
5. 凤凰/插头 通过HTTP公开MCP端点

安装

步骤1：添加依赖项

在您的私人应用程序中 mix.exs:

def deps do
  [
    {:bjjcoach_mcp_server, github: "your-org/bjjcoach_mcp_server", branch: "main"}
    # Or if using a local path during development:
    # {:bjjcoach_mcp_server, path: "../bjjcoach_mcp_server"}
  ]
end

第二步：实施提供者

在您的私人应用程序中创建您的提供者模块：

# lib/your_app/position_provider.ex
defmodule YourApp.PositionProvider do
  @behaviour BJJCoachMCP.PositionProvider

  @impl true
  def search_positions(query) do
    # Query your database
    YourApp.Repo.all(
      from p in Position,
        where: ilike(p.name, ^"%#{query}%"),
        select: %{"id" => p.id, "name" => p.name}
    )
  end

  @impl true
  def get_position_metadata(id) do
    # Fetch from your database
    position = YourApp.Repo.get!(Position, id)
    %{
      "id" => position.id,
      "name" => position.name,
      "category" => position.category,
      "synonyms" => position.synonyms,
      "description" => position.description
    }
  end
end

# lib/your_app/video_provider.ex
defmodule YourApp.VideoProvider do
  @behaviour BJJCoachMCP.VideoProvider

  @impl true
  def search_videos(position_id) do
    # Query your video database or API
    YourApp.Repo.all(
      from v in Video,
        where: v.position_id == ^position_id,
        select: %{
          "title" => v.title,
          "url" => v.url,
          "instructor" => v.instructor,
          "duration" => v.duration,
          "difficulty" => v.difficulty
        }
    )
  end
end

步骤3：配置您的提供商

在您的私人应用程序中 config/prod.exs:

config :bjjcoach_mcp_server,
  position_provider: YourApp.PositionProvider,
  video_provider: YourApp.VideoProvider

步骤4：添加到Phoenix路由器

在你的 lib/your_app_web/router.ex:

# For Phoenix applications
scope "/" do
  pipe_through :api  # Or :browser, depending on your setup

  forward "/mcp", Anubis.Server.Transport.StreamableHTTP.Plug,
    server: BJJCoachMCP.Server
end

或者，如果使用普通插头路由器：

forward "/mcp",
  to: Anubis.Server.Transport.StreamableHTTP.Plug,
  init_opts: [server: BJJCoachMCP.Server]

步骤5：访问您的MCP端点

您的MCP服务器将在以下网址提供：

https://yourdomain.com/mcp

或者为了当地发展：

http://localhost:4000/mcp

MCP工具参考

搜索位置

按姓名搜索BJJ职位。

输入：

• query （字符串，必填）-职位搜索词

输出：

[
  {"id": "butterfly_guard", "name": "Butterfly Guard"},
  {"id": "closed_guard", "name": "Closed Guard"}
]

get_position_元数据

获取特定职位的详细元数据。

输入：

• id （字符串，必填）-位置标识符

输出：

{
  "id": "butterfly_guard",
  "name": "Butterfly Guard",
  "category": "Open Guard / Seated",
  "synonyms": ["Elevated Guard", "Hook Guard"],
  "description": "A seated guard position..."
}

search_videos_for_position

查找某个职位的教学视频。

输入：

• position_id （字符串，必填）-位置标识符

输出：

[
  {
    "title": "Butterfly Guard Basics",
    "url": "https://youtube.com/...",
    "instructor": "John Danaher",
    "duration": "12:30",
    "difficulty": "beginner"
  }
]

发展

使用模拟数据在本地运行

# Install dependencies
mix deps.get

# Start in IEx
iex -S mix

# The server will start with mock providers

测试模拟提供者

# In IEx
iex> BJJCoachMCP.MockPositionProvider.search_positions("guard")
[
  %{"id" => "butterfly_guard", "name" => "Butterfly Guard"},
  %{"id" => "closed_guard", "name" => "Closed Guard"},
  %{"id" => "knee_shield", "name" => "Knee Shield"},
  ...
]

iex> BJJCoachMCP.MockVideoProvider.search_videos("butterfly_guard")
[
  %{
    "title" => "Butterfly Guard Basics - Fundamentals",
    "url" => "https://youtube.com/example/butterfly-basics",
    ...
  }
]

技术细节

构建于

• 灵药 -函数式编程语言
• 肛门MCP -模型上下文协议实现
• 插头 -Web服务器界面

MCP协议版本

该服务器实现了与Anubis MCP~>0.15.0兼容的MCP协议版本。

运输

服务器默认使用StreamableHTTP传输，这适用于大多数用例，并且与Phoenix应用程序配合良好。

贡献

这是一个公共骨架存储库。欢迎改进架构、添加更好的模拟数据或增强文档的贡献。

许可证

MIT许可证-有关详细信息，请参阅许可证文件。

相关项目

• 肛门MCP -MCP实现库
• 模型上下文协议 -MCP官方规范