MCP Server — BlueForge Developer Docs

Architecture

BlueForge MCP Server acts as a bridge between external AI agents and the BlueForge IDE. It wraps BlueForge's development tools into MCP-standard tools that any MCP-compatible client can call.

Your Agent (LLM Brain) | v MCP Client (BlueforgeConnector) | | MCP Protocol (stdio / SSE) | v BlueForge MCP Server | +-- file_read / file_write / file_edit +-- file_delete / file_list / file_search +-- terminal_exec / npm_install +-- git_status / git_diff / git_commit +-- project_info

Quick Start

Install

bash

cd src/mcp-server
npm install

Configure

Set the target project directory:

bash

export BLUEFORGE_PROJECT_DIR=/path/to/your/project

Run

bash

# Development
npm run dev

# Production
npm run build && npm start

Connect your Agent

Add to your MCP client configuration:

JSON

{
  "mcpServers": {
    "blueforge": {
      "command": "node",
      "args": ["dist/index.js"],
      "env": {
        "BLUEFORGE_PROJECT_DIR": "/path/to/project"
      }
    }
  }
}

File Operations

Read, write, edit, delete, search, and navigate project files. All paths are sandboxed within the project directory.

file_read

Read the contents of a file from the project.

Read-only

file_write

Create or overwrite a file. Auto-creates parent directories.

Write

file_edit

Search-and-replace within a file. Safer than full rewrite.

Write

file_delete

Delete a file from the project directory.

Destructive

file_list

List directory contents as a tree. Adjustable depth.

Read-only

file_search

Grep-based pattern search across project files.

Read-only

Parameters

Tool	Parameter	Type	Required	Description
`file_read`	`path`	string	Yes	Relative path from project root
`file_write`	`path`	string	Yes	Target file path
`file_write`	`content`	string	Yes	Full file content
`file_edit`	`path`	string	Yes	Target file path
	`search`	string	Yes	Exact string to find
	`replace`	string	Yes	Replacement string
`file_list`	`maxDepth`	number	No	Max traversal depth (default: 3)
`file_search`	`pattern`	string	Yes	Search pattern (regex)
`file_search`	`include`	string	No	File glob (e.g. "*.ts")

Terminal

Execute shell commands and manage npm packages within the project environment.

terminal_exec

Execute any shell command. Returns stdout, stderr, and exit code.

Execution

npm_install

Install npm packages. Supports devDependency flag.

Write

Timeout: Commands have a maximum timeout of 120 seconds. For long-running servers, use background execution patterns.

Tool	Parameter	Type	Required	Description
`terminal_exec`	`command`	string	Yes	Shell command to execute
`terminal_exec`	`timeout`	number	No	Timeout in ms (default: 30000, max: 120000)
`npm_install`	`packages`	string	Yes	Space-separated package names
`npm_install`	`dev`	boolean	No	Install as devDependency

Git Operations

git_status

Get the short git status of the project.

Read-only

git_diff

View changes. Supports staged-only mode.

Read-only

git_commit

Stage all changes and commit with a message.

Write

Project Context

project_info

Get comprehensive project metadata: package.json, dependencies, scripts, and directory structure. Call this first when starting a new development session.

Read-only

Resources

MCP Resources provide static or dynamic data that your agent can read directly without calling a tool.

URI	Description	MIME Type
`blueforge://project/package.json`	Project package.json with dependencies and scripts	application/json
`blueforge://project/structure`	Directory tree (depth 3, excludes node_modules/.git)	text/plain

Configuration

Environment Variables

Variable	Required	Default	Description
`BLUEFORGE_PROJECT_DIR`	Yes	`process.cwd()`	Absolute path to the target project directory
`BLUEFORGE_MCP_API_KEY`	No	-	API key for authentication (future)

MCP Client Config (Claude Desktop)

JSON

{
  "mcpServers": {
    "blueforge": {
      "command": "node",
      "args": ["/path/to/blueforge/src/mcp-server/dist/index.js"],
      "env": {
        "BLUEFORGE_PROJECT_DIR": "/Users/dev/my-app"
      }
    }
  }
}

Development Mode (tsx)

JSON

{
  "mcpServers": {
    "blueforge": {
      "command": "npx",
      "args": ["tsx", "/path/to/blueforge/src/mcp-server/index.ts"],
      "env": {
        "BLUEFORGE_PROJECT_DIR": "/Users/dev/my-app"
      }
    }
  }
}

Recommended System Prompt

Use this system prompt in your agent to enable autonomous development through BlueForge:

Prompt

You are a senior developer using BlueForge as your IDE.
You have access to MCP tools from the blueforge server:

FILE OPERATIONS:
  file_read(path)            - Read any project file
  file_write(path, content)  - Create or overwrite files
  file_edit(path, s, r)      - Surgical search-and-replace edits
  file_delete(path)          - Remove files
  file_list(path, maxDepth)  - Browse project structure
  file_search(pattern)       - Find code patterns

TERMINAL:
  terminal_exec(command)     - Run shell commands
  npm_install(packages, dev) - Install dependencies

GIT:
  git_status()               - Check what changed
  git_diff()                 - See exact changes
  git_commit(message)        - Commit your work

WORKFLOW:
  1. project_info()    - Understand the project
  2. file_list()       - Explore the structure
  3. file_read()       - Read relevant files
  4. file_write/edit() - Make changes
  5. terminal_exec()   - Build and test
  6. Fix any errors
  7. git_commit()      - Commit your work

Always: Understand > Plan > Implement > Verify > Commit

Security

Protection	Description
Path Sandboxing	All file paths resolved relative to `BLUEFORGE_PROJECT_DIR`. Traversal attempts are blocked.
Command Scope	Shell commands execute within the project directory only.
Timeout Limits	Terminal commands max out at 120 seconds.
Output Buffer	stdout capped at 5MB to prevent memory exhaustion.
API Key Auth	Optional `BLUEFORGE_MCP_API_KEY` for authenticated access (future).

Node_modules and .git directories are automatically excluded from file_list and file_search results.