# instant-mcp

[English](README.md) | [한국어](README.ko.md)

A local mock MCP server for people building against the Model Context Protocol.
Write a tool in the browser, save it, and it is immediately available on an MCP
endpoint. There is no restart or deploy step.

Point your MCP client at `http://127.0.0.1:4100/mcp/default` and start working.

![Tool editor with a live test run](docs/screenshots/editor.jpg)

```ts
import { defineTool } from "instant-mcp";

export default defineTool({
  description: "Look up a user by name",
  inputSchema: {
    type: "object",
    properties: { name: { type: "string" } },
    required: ["name"],
  },
  handler(args: { name: string }, ctx) {
    return ctx.db.query("SELECT * FROM users WHERE username = ?", [args.name]);
  },
});
```

## Features

- Hot reload. Save a tool and the endpoint serves the new version on the next
  request. Editing in the web UI and editing the file directly both work.
- Multiple endpoints. Group tools and serve each group at `/mcp/<slug>`, so
  different clients can see different tool sets.
- A mock database. Create SQLite tables in the UI and read or write them from
  tool code through `ctx.db`.
- A call log. Every MCP call is recorded with its arguments, result, errors and
  duration, so you can see the arguments a client actually sent.
- A control endpoint. Optionally expose instant-mcp itself over MCP so a coding
  agent can author tools, wire endpoints and read the call log.

Everything runs locally with no authentication. The server binds to `127.0.0.1`
only.

## Quick start

Requires Node 20 or newer.

```bash
git clone https://github.com/jhleee/instant-mcp.git
cd instant-mcp
npm install
npm run build     # build the web UI once
npm start         # http://127.0.0.1:4100
```

The first run copies two example tools into `data/tools/`.

Register it with an MCP client:

```json
{
  "mcpServers": {
    "instant-mcp": {
      "type": "http",
      "url": "http://127.0.0.1:4100/mcp/default"
    }
  }
}
```

For UI development, `npm run dev` runs the server and Vite together. The UI is on
`http://127.0.0.1:5173` and proxies API and MCP traffic to port 4100.

## Writing tools

A tool is a directory under `data/tools/` with an `index.ts` that default-exports
one module. The authoring API comes from the `instant-mcp` module, so there is no
need for relative paths into the server.

`defineTool` returns its argument unchanged. It exists for typing: use it and
`ctx` is inferred without an annotation. A plain `export default { ... }` also
works.

- A handler that returns a string sends it as-is. Any other value is
  JSON-stringified. Return `{ content: [...] }` to build the MCP payload
  yourself.
- `inputSchema` is used for validation, not just documentation. A call missing a
  required field is rejected before the handler runs.
- Saving recompiles and reloads the tool, whether you save from the web UI or
  edit the file directly.

### What `ctx` can do

The full API is in [`sdk/index.d.ts`](sdk/index.d.ts). The server implementation
is type-checked against that file and the web editor loads the same file, so the
documentation stays in step with the behaviour.

There are three ways to read it:

1. Editor autocomplete. Type `ctx.` inside a handler to get the methods with
   their docs and examples.
2. The Context API button in the sidebar footer, which renders the declaration
   file.
3. `npm run typecheck`, which covers `data/tools/**` along with the server.

`ctx.db` is the only route to the mock tables:

| Method | Purpose |
|---|---|
| `tables()` | Names of all mock tables |
| `all(table, limit?)` | Every row, up to `limit` (default 500) |
| `query(sql, params?)` | Read-only SELECT with `?` placeholders |
| `insert(table, values)` | Insert a row, returns the new `id` |
| `update(table, id, values)` | Update only the columns given |
| `delete(table, id)` | Delete a row |

## Groups and endpoints

Tools belong to groups, and each group is served at its own endpoint. New tools
join the `default` group automatically. Endpoints use stateless Streamable HTTP
and are rebuilt per request, so hot reloads and enable/disable changes take
effect right away.

![Groups list showing the default endpoint and its tools](docs/screenshots/groups.jpg)

## Mock tables

Create tables and edit rows under Mock Tables in the sidebar. Every table gets an
auto-increment `id`. Names beginning with `_` and the `sqlite_` prefix are
rejected to protect the metadata tables, and identifiers are validated before
they reach SQL.

## Call log

Every tool call arriving over MCP is recorded: time, group, tool, arguments,
result, error flag and duration. Read it under Call Log in the sidebar, or with
`get_call_log` on the control endpoint.

This matters when you are testing someone else's client, because it shows the
arguments that were sent rather than the ones that were intended. Calls rejected
by argument validation are logged too. The log keeps the most recent 2000 entries
and truncates large payloads.

![Call log with a successful call and rejected calls](docs/screenshots/call-log.jpg)

## Control endpoint (`/mcp/_control`)

An optional endpoint that exposes instant-mcp itself over MCP, so a coding agent
can build and debug a mock server.

```bash
npm run start:control        # or INSTANT_MCP_CONTROL=1 npm start
```

```json
{
  "mcpServers": {
    "instant-mcp-control": {
      "type": "http",
      "url": "http://127.0.0.1:4100/mcp/_control"
    }
  }
}
```

### Tools

| Tool | Purpose |
|---|---|
| `describe_workspace` | One call returns tools, groups, endpoint URLs and tables |
| `read_tool` | A tool's source |
| `write_tool` | Create or update. Returns `loadError`, so the caller knows whether the code compiled |
| `delete_tool` | Remove a tool |
| `run_tool` | Execute directly, bypassing MCP, to check a tool before handing over an endpoint |
| `write_group` / `delete_group` | Manage endpoints. `write_group` returns the URL |
| `write_table` / `drop_table` | Mock schema |
| `seed_table` | Bulk insert (`append` or `replace`) |
| `query_sql` | Read-only SELECT |
| `get_call_log` | What clients actually sent |

There is no per-row CRUD. Inserting twenty rows should be one `seed_table` call
rather than twenty round trips.

### Resources

- `instant-mcp://sdk` is the tool authoring API. Read it before writing tool code
  and there is nothing to guess about `ctx`.
- `instant-mcp://tools/{name}` is a tool's source.
- `instant-mcp://groups/{slug}` is the `tools/list` payload that endpoint serves,
  which is what a client will see rather than internal state.

### Isolation

The control surface is a fixed endpoint outside the normal group namespace, so an
agent cannot disable the tools it is calling through:

- Slugs starting with `_` are reserved, so no group can shadow `_control`.
- Control tools are built into the server rather than stored under `data/tools/`,
  so `write_tool` and `delete_tool` cannot reach them and they cannot be
  disabled.
- `_control` never appears in the group list, so it cannot be edited or deleted.

`npm run smoke:guards` checks all four.

### Security

This endpoint is effectively an arbitrary code execution API. `write_tool` writes
files under `data/tools/` and that code runs unsandboxed inside the server
process, which is why it is off until you turn it on. The web UI has the same
power, but exposing it over MCP means any client that knows the URL has it too.

Enable it for local mock work only.

## Project layout

```
sdk/index.d.ts     the tool authoring API
sdk/index.js       defineTool runtime
server/
  index.ts         entry point: REST API, MCP and the static UI on one port
  db.ts            SQLite schema and mock table CRUD
  toolLoader.ts    esbuild transpile, dynamic import, chokidar hot reload
  workspace.ts     tool/group/table operations shared by REST and control MCP
  mcp.ts           per-group MCP server (tools/list, tools/call)
  control.ts       control MCP: 12 tools and 3 resources
  callLog.ts       MCP call recording
  toolContext.ts   the ctx injected into tool handlers
  routes/          apiRoute.ts (REST), mcpRoute.ts (/mcp/:slug)
web/               Vite, React, shadcn/ui, Monaco
examples/tools/    example tools, copied into data/tools on first run
data/              your workspace: tool code, SQLite db, build output (untracked)
```

## Scripts

| Command | Purpose |
|---|---|
| `npm run dev` | Server and Vite together |
| `npm start` | Server only, serving the built UI |
| `npm run start:control` | Also enable the control endpoint |
| `npm run build` | Build the web UI |
| `npm run typecheck` | Type-check everything, including your tools |
| `npm run smoke` | Connect an MCP client to `/mcp/default` |
| `npm run smoke:control` | Author a tool, wire an endpoint, call it, read the log |
| `npm run smoke:guards` | Control endpoint isolation checks |

## Limitations

Tool code runs unsandboxed in the server process, so only load code you trust.
Sandboxing with `vm` is planned but not implemented.

The transport is stateless, so there is no `notifications/tools/list_changed`
push and clients have to re-list to see new tools. Each request rebuilds the
server, so re-listing always returns current state.

## Contributing

Issues and pull requests are welcome. Please run `npm run typecheck` and
`npm run build` before opening a PR.

## License

[MIT](LICENSE)