bjjcoach-mcp-server

tspenov/bjjcoach-mcp-server

3.1

If you are the rightful owner of bjjcoach-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

The BJJ Coach MCP Server is a Model Context Protocol server that provides AI assistants with access to Brazilian Jiu-Jitsu position and video data.

Tools
3
Resources
0
Prompts
0

BJJ Coach MCP Server

A Model Context Protocol (MCP) server providing AI assistants with access to BJJ (Brazilian Jiu-Jitsu) position and video data. This is a public skeleton repository designed to be used as a library in a private BJJ Coach application.

Overview

This MCP server exposes three tools to AI assistants:

  • search_positions - Search for BJJ positions by name
  • get_position_metadata - Get detailed information about a position
  • search_videos_for_position - Find instructional videos for a position

The skeleton uses mock providers that return sample data, making it safe for public repositories. Your private application should implement real providers with access to your actual data.

Architecture

Separation of Concerns

This project cleanly separates the public MCP server interface from private data implementation:

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)

How It Works

  1. Behaviours define the contract that providers must implement
  2. Mock providers are configured by default (safe for public repo)
  3. Your private app overrides the config to use real providers
  4. MCP Server calls whichever provider is configured
  5. Phoenix/Plug exposes the MCP endpoint via HTTP

Installation

Step 1: Add to Dependencies

In your private application's 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

Step 2: Implement Providers

Create your provider modules in your private application:

# 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

Step 3: Configure Your Providers

In your private app's config/prod.exs:

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

Step 4: Add to Phoenix Router

In your 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

Or if using a plain Plug router:

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

Step 5: Access Your MCP Endpoint

Your MCP server will be available at:

https://yourdomain.com/mcp

Or for local development:

http://localhost:4000/mcp

MCP Tools Reference

search_positions

Search for BJJ positions by name.

Input:

  • query (string, required) - Search term for positions

Output:

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

get_position_metadata

Get detailed metadata for a specific position.

Input:

  • id (string, required) - Position identifier

Output:

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

search_videos_for_position

Find instructional videos for a position.

Input:

  • position_id (string, required) - Position identifier

Output:

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

Development

Running Locally with Mock Data

# Install dependencies
mix deps.get

# Start in IEx
iex -S mix

# The server will start with mock providers

Testing 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",
    ...
  }
]

Technical Details

Built With

  • Elixir - Functional programming language
  • Anubis MCP - Model Context Protocol implementation
  • Plug - Web server interface

MCP Protocol Version

This server implements MCP protocol version compatible with Anubis MCP ~> 0.15.0.

Transport

The server uses StreamableHTTP transport by default, which is suitable for most use cases and works well with Phoenix applications.

Contributing

This is a public skeleton repository. Contributions that improve the architecture, add better mock data, or enhance documentation are welcome.

License

MIT License - See LICENSE file for details.

Related Projects