Mcpex

MCPEX is an Elixir implementation of the Machine Chat Protocol (MCP).

Development Setup

Requirements

• Elixir 1.18.3 with Erlang/OTP 27
• The project includes a .tool-versions file for use with asdf

Automated Setup

For a quick setup in the development VM, run:

./setup.sh

This script will:

1. Install asdf version manager
2. Install Erlang 27.0 and Elixir 1.18.3 using asdf (note: Erlang compilation may take 10-20 minutes)
3. Install Hex package manager and Rebar
4. Fetch project dependencies
5. Compile the project
6. Run tests to verify the setup

Note: Erlang compilation can take a significant amount of time (10-20 minutes) as it builds from source. You can monitor the progress in another terminal with:

tail -f ~/.asdf/plugins/erlang/kerl-home/builds/asdf_*/otp_build*.log

Using the Makefile

The project includes a Makefile to simplify common development tasks:

# Setup development environment
make setup

# Get dependencies
make deps

# Compile the project
make compile

# Run tests
make test

# Run the application
make run

# Format code
make format

# Run static code analysis
make lint

# Generate documentation
make docs

# Docker tasks
make docker-build
make docker-run
make docker-stop

# Show all available commands
make help

Manual Setup

If you prefer to set up manually:

1. Install asdf version manager:

   git clone https://github.com/asdf-vm/asdf.git ~/.asdf --branch v0.13.1
   echo '. "$HOME/.asdf/asdf.sh"' >> ~/.bashrc
   echo '. "$HOME/.asdf/completions/asdf.bash"' >> ~/.bashrc
   source ~/.asdf/asdf.sh
   

2. Install Erlang and Elixir using asdf:

   # Install required dependencies for building Erlang
   apt-get update
   apt-get install -y build-essential autoconf m4 libncurses5-dev libwxgtk3.2-dev libwxgtk-webview3.2-dev libgl1-mesa-dev libglu1-mesa-dev libpng-dev libssh-dev unixodbc-dev xsltproc fop libxml2-utils libncurses-dev openjdk-17-jdk
   
   # Install asdf plugins
   asdf plugin add erlang
   asdf plugin add elixir
   
   # Install versions from .tool-versions file
   asdf install
   

3. Install Hex package manager and Rebar:

   mix local.hex --force
   mix local.rebar --force
   

4. Fetch dependencies:

   mix deps.get
   

5. Compile the project:

   mix compile
   

6. Run tests:

   mix test
   

Running the Application

Running Locally

To start the application locally:

mix run --no-halt

Running with Docker

The project includes Docker configuration for easy containerized deployment:

1. Build and start the container:

   docker-compose up
   

2. Or build and run in detached mode:

   docker-compose up -d
   

3. To stop the container:

   docker-compose down
   

Using as a Dependency

If available in Hex, the package can be installed by adding mcpex to your list of dependencies in mix.exs:

def deps do
  [
    {:mcpex, "~> 0.1.0"}
  ]
end

Documentation can be generated with ExDoc and published on HexDocs. Once published, the docs can be found at https://hexdocs.pm/mcpex.

JSON Handling

MCPEX uses Elixir's built-in JSON module (available since Elixir 1.18) for all JSON encoding and decoding operations. Please do not add Jason or other JSON libraries as dependencies when working with this project.

For more details on JSON usage in this project, see docs/json_usage.md.