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

​
Running tests

​
Linting

Mcpjungle uses golangci-lint.
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

​
Database development

​
SQLite

When running with SQLite, you can inspect the local database using sqlite3:
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:

​
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:
Then update the filesystem server config accordingly:

​
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:
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:
  1. Release with goreleaser:
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.