> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mcpjungle.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Development guide

> Development setup, build and test workflows, architecture orientation, and release operations for mcpjungle contributors.

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:

* [CLI commands](https://github.com/mcpjungle/MCPJungle/tree/main/cmd)
* [HTTP API server](https://github.com/mcpjungle/MCPJungle/blob/main/internal/api/server.go)
* [MCP proxy server](https://github.com/mcpjungle/MCPJungle/blob/main/internal/service/mcp/proxy.go)

## Building and testing

### Local development build

```bash theme={null}
# 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

```bash theme={null}
# 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`.

```bash theme={null}
golangci-lint run
golangci-lint run --fix
```

See the [golangci-lint installation docs](https://golangci-lint.run/docs/welcome/install/) 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

```bash theme={null}
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`:

```bash theme={null}
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](https://github.com/modelcontextprotocol/inspector) is useful when testing and debugging MCP interactions:

```bash theme={null}
npx @modelcontextprotocol/inspector
```

## Docker filesystem access

For normal usage, the canonical explanation lives in [Register a stdio MCP server](/guides/register-stdio-servers#running-in-docker-filesystem-access).

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`:

```yaml theme={null}
volumes:
  - ${HOME}:/host/home:ro
  - /path/to/your/project:/host/project:ro
  - /tmp:/host/tmp:rw
```

Then update the filesystem server config accordingly:

```json theme={null}
{
  "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 theme={null}
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:

```bash theme={null}
git tag -a 0.1.0 -m "Release version 0.1.0"
git push origin 0.1.0
```

2. Release with goreleaser:

```bash theme={null}
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

* Check [GitHub Issues](https://github.com/mcpjungle/MCPJungle/issues)
* Join [Discord](https://discord.gg/CapV4Z3krk)
* Open a GitHub Discussion for design or workflow questions

## Contribution guide

For workflow and contribution expectations, see the [Contributing guide](/developers/contributing).