# MuleSoft Code MCP

Model Context Protocol (MCP) is a standardized way for LLMs to use external systems through tools. This repository provides a focused remote MCP server for MuleSoft APIs so agents can discover operations and execute validated API calls with a fixed low-context tool surface.

Design references:
- [Cloudflare Code Mode MCP](https://blog.cloudflare.com/code-mode-mcp/)
- [Anthropic: Building Effective Agents (advanced tool use)](https://www.anthropic.com/engineering/building-effective-agents)

The server supports `streamable-http` transport via `/mcp`.

## Server in this Repository

| Server | Description | URL |
| --- | --- | --- |
| `mulesoft-code-mcp` | Search + execute over MuleSoft operations with OAuth and write guardrails | `http://127.0.0.1:3000/mcp` |

## Tools Exposed

| Tool | Purpose | Typical use |
| --- | --- | --- |
| `search` | Finds ranked operations from Exchange portal + OpenID context | "list assets", "exchange api", "oauth token" |
| `execute` | Validates and executes operation by `operation_id` | Read and write calls with typed validation |
| `auth_status` | Returns auth status for current caller | Preflight before `execute` |

## Why Better Than Official MCP Patterns

Compared to official/provider MCP servers that expose many endpoint-specific tools, this implementation is better for agent execution quality:

- Lower context pressure: fixed `3` tools instead of endpoint-tool explosion.
- Better tool selection: agent maps intent with `search`, then executes one explicit `operation_id`.
- Stronger safety: writes require both server policy and per-request confirmation token.
- Better runtime behavior: response truncation, read caching, and persisted catalog cache reduce latency and token waste.

## Access from Any MCP Client

If your MCP client supports remote MCP directly:

```json
{
  "mcpServers": {
    "mulesoft-code-mcp": {
      "transport": "streamable_http",
      "url": "http://127.0.0.1:3000/mcp",
      "headers": {
        "x-user-id": "default"
      }
    }
  }
}
```

If your client needs a command bridge:

```json
{
  "mcpServers": {
    "mulesoft-code-mcp": {
      "command": "npx",
      "args": ["mcp-remote", "http://127.0.0.1:3000/mcp"],
      "env": {
        "MCP_REMOTE_HEADERS": "{\"x-user-id\":\"default\"}"
      }
    }
  }
}
```

## Quick Start

```bash
cd mulesoft
npm install
npm run build
npm test
```

Seed access token from environment:

```bash
MULESOFT_ACCESS_TOKEN='<token>' npm run seed:token
```

Start server:

```bash
TOKEN_STORE_PATH=./data/tokens.integration.json \
TOKEN_ENCRYPTION_KEY_BASE64='<seed-output-key>' \
PORT=3000 HOST=127.0.0.1 npm run dev
```

Smoke test:

```bash
curl -sS http://127.0.0.1:3000/healthz
MCP_URL=http://127.0.0.1:3000/mcp USER_ID=default npm run smoke:mcp
```

## Tool Calling Flow

1. Call `auth_status`.
2. Call `search` with intent (for example, `list exchange assets`).
3. Pick an `operation_id`.
4. Call `execute` with required params.
5. For writes: call `dry_run=true`, then replay with `confirm_write_token` and `ALLOW_WRITES=true`.

Example `search` input:

```json
{
  "query": "list exchange assets",
  "limit": 5
}
```

Example read `execute` input:

```json
{
  "operation_id": "GET /exchange/api/v2/assets"
}
```

Example write `execute` dry run:

```json
{
  "operation_id": "DELETE /exchange/api/v2/assets/{assetId}",
  "path_params": {
    "assetId": "my-asset"
  },
  "dry_run": true
}
```

## Configuration

Key environment variables:

- `ALLOW_WRITES` (default `false`)
- `REQUEST_TIMEOUT_MS`
- `MAX_RETRIES`
- `CATALOG_CACHE_PATH`
- `READ_CACHE_TTL_MS`
- `EXECUTE_MAX_BODY_BYTES`
- `EXECUTE_BODY_PREVIEW_CHARS`

See `.env.example` for the full set.

## Safety Model

- Mutating methods are blocked unless `ALLOW_WRITES=true`.
- Mutating calls require `confirm_write_token` from `dry_run` for exact request replay.
- Sensitive headers and body fields are redacted.

## Performance Model

- Fixed 3-tool MCP surface to keep context small.
- Persisted catalog cache enables fast startup and asynchronous refresh.
- Conditional refresh for upstream metadata where available.
- Short TTL cache for repeated read calls (`GET` / `HEAD`).
- Execute body truncation controls context overhead.

## Troubleshooting

- MCP Inspector connect failure: confirm URL is `http://127.0.0.1:3000/mcp` and server is running.
- `AUTH_REQUIRED`: seed token or complete OAuth bootstrap.
- Write blocked: set `ALLOW_WRITES=true` and use returned `confirm_write_token`.
- Sparse search results: include concrete resource terms (`exchange`, `assets`, `oauth`).

## Development

- Source: `src`
- Tests: `tests`
- References: `REFERENCES.md`