Skip to main content
This guide covers development setup and technical workflows for contributors and maintainers.

​
Principles

Mcpjungle follows minimalism. When implementing a feature or fixing an issue, prefer the least amount of change required to ship something that works well without breaking other behavior. Improvements beyond that should be guided by user feedback, not by the urge to add complexity.

​
Architecture overview

Mcpjungle consists of several main components:
  • CLI: command-line interface for managing MCP servers and tools in cmd/
  • HTTP API: REST API for management workflows in internal/api/
  • MCP Gateway server: MCP protocol handling in internal/service/mcp/
  • Database layer: SQLite and PostgreSQL persistence in internal/db/

​
Codebase entry points

Good places to orient yourself:

​
Building and testing

​
Local development build

# Refresh the embedded dashboard bundle first
bash ./scripts/build-dashboard.sh

# Single binary for your current system
goreleaser build --single-target --clean --snapshot

# Test the full release assets (binaries and docker image) without publishing
goreleaser release --clean --snapshot --skip publish

# Binaries for all supported platforms
goreleaser release --snapshot --clean

​
Running tests

# Refresh dashboard assets before testing Go-served UI behavior
bash ./scripts/build-dashboard.sh

# Run all tests
go test ./...

# Run tests with coverage
go test -cover ./...

# Run a specific package
go test ./internal/service/mcp

# Run the sanity test script
./scripts/test-mcpjungle.sh

​
Linting

Mcpjungle uses golangci-lint. 
golangci-lint run
golangci-lint run --fix
See the golangci-lint installation docs if needed.

​
Development environment setup

​
Prerequisites

  • Go 1.21 or later
  • Docker and Docker Compose
  • SQLite3 for local development
  • Node.js if you want to use MCP Inspector

​
Quick start

git clone https://github.com/mcpjungle/MCPJungle.git
cd MCPJungle

# Fresh clones need the generated dashboard bundle before Go tests/builds.
# This installs frontend deps as needed and copies the built assets into
# internal/dashboardui/dist for Go's //go:embed step.
bash ./scripts/build-dashboard.sh

docker-compose up -d

goreleaser build --single-target --clean --snapshot

​
Database development

​
SQLite

When running with SQLite, you can inspect the local database using sqlite3: 
sqlite3 mcpjungle.db

.tables
SELECT * FROM mcp_servers;
SELECT * FROM tools;
For backward compatibility, Mcpjungle still reads existing mcp.db files if they exist, but new databases are created as mcpjungle.db. If you start the server with --sqlite-db-path or SQLITE_DB_PATH, inspect that configured file path instead.

​
PostgreSQL

When running with Docker Compose, you can inspect PostgreSQL through pgAdmin:
  1. Open http://localhost:5050
  2. Log in with username admin@admin.com and password admin
  3. Add a database server with:
    • Host: db
    • Port: 5432
    • Username: mcpjungle
    • Password: mcpjungle
    • Database: mcpjungle

​
MCP server testing

MCP Inspector is useful when testing and debugging MCP interactions: 
npx @modelcontextprotocol/inspector

​
Docker filesystem access

For normal usage, the canonical explanation lives in Register a stdio MCP server. For contributors changing the local Docker setup itself, the only thing to keep in mind is that the Compose files mount host paths inside the container and the filesystem MCP config must match those mount points. For example, you can narrow the volume mounts in docker-compose.yaml: 
volumes:
  - ${HOME}:/host/home:ro
  - /path/to/your/project:/host/project:ro
  - /tmp:/host/tmp:rw
Then update the filesystem server config accordingly: 
{
  "name": "filesystem",
  "transport": "stdio",
  "description": "filesystem mcp server",
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-filesystem", "/host/home"]
}

​
Release process

​
Frontend dashboard build integration

The dashboard source lives in web/dashboard, but the Go server serves the embedded bundle from internal/dashboardui/dist. Use the shared script below whenever you want the Go-served dashboard at http://localhost:8080/ to reflect your latest frontend changes: 
bash ./scripts/build-dashboard.sh
That script:
  1. installs frontend dependencies with npm ci if web/dashboard/node_modules is missing
  2. runs npm run build in web/dashboard
  3. replaces internal/dashboardui/dist with the fresh Vite build output
After running it, restart go run . start, go build, or any other Go process that embeds the dashboard assets.

​
Creating a release

  1. Create and push a tag:
git tag -a 0.1.0 -m "Release version 0.1.0"
git push origin 0.1.0
  1. Release with goreleaser:
export GITHUB_TOKEN="<your GH token>"
echo $GITHUB_TOKEN | docker login ghcr.io -u <your-github-username> --password-stdin

goreleaser release --clean
This publishes release artifacts and the Homebrew distribution. GoReleaser runs bash ./scripts/build-dashboard.sh in its before.hooks before the test, lint, and build steps, so release artifacts automatically include a fresh embedded dashboard bundle.

​
Troubleshooting

Common issues:
  1. Build failures: check Go version and dependencies
  2. Database connection problems: verify PostgreSQL or SQLite access
  3. MCP registration failures: verify the upstream server is reachable
  4. Docker filesystem access issues: verify the /host mount

​
Getting help

​
Contribution guide

For workflow and contribution expectations, see the Contributing guide.