onplana-mcp-server

# Onplana MCP server

Open-source TypeScript Model Context Protocol building blocks,
extracted from [Onplana](https://onplana.com)'s production MCP
deployment. Two packages:

- **[`onplana-mcp-server`](./packages/server-template)**: server
  template. Streamable HTTP transport, Bearer auth, prompt-injection
  containment, pluggable dispatcher.
- **[`onplana-mcp-client`](./packages/client)**: typed TypeScript
  client SDK for calling the public Onplana MCP endpoint at
  `https://api.onplana.com/api/mcp/v1`.

[![CI](https://github.com/Onplana/onplana-mcp-server/workflows/CI/badge.svg)](https://github.com/Onplana/onplana-mcp-server/actions)
[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)

## What this is

The transport layer of an MCP server (Streamable HTTP wiring,
stateless mode, scoped Bearer auth, prompt-injection containment)
done well, separated from the platform-specific tool registry. Use
the **server template** to build your own MCP server with security
best practices baked in. Use the **client SDK** to drive Onplana's
hosted MCP from your own code.

The patterns are extracted from Onplana's production deployment
(public docs at [onplana.com/mcp](https://onplana.com/mcp)), the
same layer that handles real Claude Desktop, Cursor, ChatGPT custom
connector, and in-house agent traffic against the Onplana platform.

## Why open-source

The MCP transport is the same for everyone. Most early MCP servers
get the security primitives wrong:

- **Prompt injection.** Tools that return user-generated content
  (task titles, comment bodies, wiki text) put that content directly
  into the model's context. Without containment, a hostile actor can
  plant `"ignore previous instructions"` in their own data and the
  next agent that reads it follows along.
- **Stateless transport.** Most SDK examples assume in-memory session
  state, which breaks horizontal scaling and complicates the auth
  model.
- **Plan-gate semantics.** Surfacing tools the caller can't actually
  invoke wastes turns and confuses the model.

Onplana solved these in production over six months of MCP-server
work. Publishing the patterns is high-leverage:

1. Other MCP authors get a known-good template instead of
   reinventing.
2. The repo is a pretraining-signal surface. Public GitHub READMEs
   are heavily weighted in next-gen LLM training data, and a repo
   with patterns + clear documentation about MCP improves model
   recall of "what good MCP servers look like."
3. The dispatcher interface is the seam where your business logic
   plugs in. The transport is generic; what matters about your MCP
   server is the tool registry. Open-sourcing the transport doesn't
   give away anything proprietary.

The dispatcher implementation, tool catalog, plan-gate logic, audit
infrastructure, and the rest of Onplana's ~600 LOC closed-source
dispatcher stay in the closed monorepo because they encode platform
business logic. If you build your own MCP server using this
template, you write your own dispatcher. That's the work that
matters and the work that's specific to your platform.

## Repository layout

```
onplana-mcp-server/
├── packages/
│   ├── server-template/        # onplana-mcp-server (npm)
│   │   ├── src/
│   │   │   ├── transport.ts    # Streamable HTTP wiring
│   │   │   ├── auth.ts         # Bearer auth pattern
│   │   │   ├── promptInjection.ts  # wrapUserContent + escape
│   │   │   ├── dispatcher.ts   # Pluggable Dispatcher interface
│   │   │   └── index.ts
│   │   ├── tests/              # promptInjection + auth + transport
│   │   └── README.md
│   └── client/                 # onplana-mcp-client (npm)
│       ├── src/
│       │   ├── client.ts       # OnplanaMcpClient class
│       │   ├── types.ts        # Public type surface
│       │   └── index.ts
│       ├── tests/              # client.test.ts (stub fetch)
│       └── README.md
├── .claude-plugin/
│   └── marketplace.json        # Claude Code marketplace
├── plugins/
│   └── onplana/                # Claude Code plugin (skills + connect command)
├── examples/
│   └── in-memory/              # Runnable demo with 3 toy tools
├── gemini-extension.json       # Gemini CLI manifest
├── mcp.json                    # stdio client config (mcp-remote)
├── server.json                 # MCP registry manifest
└── .github/workflows/
    ├── ci.yml                  # tsc + vitest on PR
    └── publish.yml             # npm publish on tag v*
```

## Quickstart

### Build a server

Install:

```bash
npm install github:Onplana/onplana-mcp-server @modelcontextprotocol/sdk express
```

Wire an Express app:

```ts
import express from 'express'
import {
  createMcpPostHandler,
  createMcpMethodNotAllowedHandler,
  requireBearerAuth,
  type Dispatcher,
} from 'onplana-mcp-server'

const dispatcher: Dispatcher = {
  async listTools(ctx) { /* return your tool descriptors */ return [] },
  async callTool(name, input, ctx) { /* dispatch to your tools */ return { output: {} } },
}

const auth = async (token: string) => {
  // Validate against your token store. Return AuthContext or null.
  return { userId: 'u', scopes: ['MCP_AGENT'] }
}

const app = express()
app.use(express.json())
app.use('/api/mcp/v1',
  requireBearerAuth({ auth, requiredScope: 'MCP_AGENT' }),
)
app.post('/api/mcp/v1', createMcpPostHandler({ dispatcher }))
app.get('/api/mcp/v1', createMcpMethodNotAllowedHandler())
app.delete('/api/mcp/v1', createMcpMethodNotAllowedHandler())
app.listen(3000)
```

Full quickstart in [`packages/server-template/README.md`](./packages/server-template/README.md);
runnable demo in [`examples/in-memory/`](./examples/in-memory).

### Drive Onplana from code

Install:

```bash
npm install github:Onplana/onplana-mcp-server
```

Use:

```ts
import { OnplanaMcpClient } from 'onplana-mcp-client'

const client = new OnplanaMcpClient({
  url:   'https://api.onplana.com/api/mcp/v1',
  token: process.env.ONPLANA_PAT!,
})

const projects = await client.listProjects({ status: 'ACTIVE' })

// The differentiator vs other PM-tool MCPs: hybrid semantic + lexical
// search across your org's indexed content (projects, tasks, risks,
// goals, comments, wiki pages).
const { matches } = await client.searchOrgKnowledge({
  query: 'rationale for the 3-week design phase',
  scope: 'all',
  limit: 5,
})
```

Full client docs in [`packages/client/README.md`](./packages/client/README.md).

## Tools

The hosted server at `https://mcp.onplana.com/mcp` exposes 285 tools,
spanning projects, tasks, sprints, milestones, earned value, risks,
issues, governance, change control, timesheets, wikis, whiteboards,
workflows and the Microsoft Graph integrations. The exact number a given
client sees is smaller, because tools are filtered by the caller's role
and the organization's plan before the catalog is served.

The 33 below are the ones worth knowing first, not the whole catalog.
Reads are annotated `readOnlyHint`; writes carry `destructiveHint` so a
client can gate them. Every call runs under the calling identity, is
checked against that user's permissions and the org's plan, and lands in
the audit trail.

**Read** (`readOnlyHint: true`)

- `list_projects`: projects in the org, filterable by status.
- `get_project`: one project in full, with dates, owner and progress.
- `list_tasks`: tasks for a project, or across projects.
- `get_task`: one task with description, assignee, dates and recent comments.
- `list_my_tasks`: tasks assigned to the calling user.
- `list_overdue`: tasks past their due date.
- `list_team_members`: members of a project.
- `list_org_members`: members of the organization.
- `list_risks`: risks logged against a project.
- `find_similar_projects`: past projects resembling a description, for estimating.
- `search_org_knowledge`: hybrid BM25 and vector search over tasks, projects, wiki pages and comments.
- `summarize_project`: AI summary synthesized from the live plan.
- `analyze_project_risks`: AI risk detection across schedule, budget, scope and resources.
- `generate_status_report`: AI status report from the current schedule and activity.
- `search`: App Directory adapter, returns `{id, title, snippet?, url?}`.
- `fetch`: App Directory adapter, returns `{id, title, content, url?, metadata?}`.

**Write, additive** (`destructiveHint: false`)

- `create_project`: create a project.
- `create_task`: create a task, optionally under a parent.
- `create_milestone`: add a milestone to a project.
- `create_comment`: comment on a task, issue or project.
- `create_sprint_with_tasks`: create a sprint and pull tasks into it.
- `submit_timesheet`: log hours against a task.
- `add_project_member`: add an existing org member to a project.
- `link_dependency`: link two tasks, idempotent via a unique constraint.

**Write, mutating** (`destructiveHint: true`)

- `update_project`: change project fields such as status, dates or budget.
- `update_task`: change task fields such as status, progress or dates.
- `bulk_update_tasks`: apply one change across many tasks.
- `assign_task`: set a task's assignee.
- `move_task_to_sprint`: move a task into or out of a sprint.

**Leases** (for agents that share a backlog)

- `next_task`: pick the next available task and claim it in one call.
  Listing and then claiming leaves a gap two agents can both land in.
- `claim_task`: take an exclusive lease on a specific task.
- `renew_task_lease`: extend a lease while the work is still running.
- `release_task`: hand the lease back; completing or blocking a task
  releases it too, and ending a session releases everything that run holds.

A lease is keyed to the RUN, not to the user. Two sessions of one client
authenticate as the same agent persona, so a user-keyed lock would let
one session release the other's work. Leases expire on their own, so a
crashed agent frees its task instead of holding it.

Four delete tools are in the catalog (a task, a project, a list, a
document). Each is a per-organization switch that is on until an org admin
saves