Onplana

Conecte Claude, ChatGPT, Cursor, Gemini e GitHub Copilot ao seu portfólio de projetos Onplana. 27 ferramentas, autenticação OAuth + PAT, trilha de auditoria completa.

GitHub

Experimente este MCPPatrocinado

Documentação

Servidor MCP Onplana

Blocos de construção de Protocolo de Contexto de Modelo (MCP) em TypeScript de código aberto, extraídos da implantação de MCP de produção da Onplana. Dois pacotes:

onplana-mcp-server: modelo de servidor. Transporte HTTP transmitível, autenticação Bearer, contenção de injeção de prompt, despachante plugável.
onplana-mcp-client: SDK de cliente TypeScript tipado para chamar o endpoint público de MCP da Onplana em https://api.onplana.com/api/mcp/v1.

O que é isto

A camada de transporte de um servidor MCP (conexão HTTP transmitível, modo sem estado, autenticação Bearer com escopo, contenção de injeção de prompt) bem feita, separada do registro de ferramentas específico da plataforma. Use o modelo de servidor para construir seu próprio servidor MCP com práticas recomendadas de segurança incorporadas. Use o SDK de cliente para conduzir o MCP hospedado da Onplana a partir do seu próprio código.

Os padrões são extraídos da implantação de produção da Onplana (documentação pública em onplana.com/mcp), a mesma camada que lida com tráfego real de Claude Desktop, Cursor, conector personalizado do ChatGPT e agentes internos contra a plataforma Onplana.

Por que código aberto

O transporte MCP é o mesmo para todos. A maioria dos primeiros servidores MCP erra nos primitivos de segurança:

Injeção de prompt. Ferramentas que retornam conteúdo gerado pelo usuário (títulos de tarefas, corpos de comentários, texto de wiki) colocam esse conteúdo diretamente no contexto do modelo. Sem contenção, um ator hostil pode plantar "ignore previous instructions" em seus próprios dados e o próximo agente que os ler seguirá adiante.
Transporte sem estado. A maioria dos exemplos de SDK assume estado de sessão em memória, o que quebra a escala horizontal e complica o modelo de autenticação.
Semântica de portão de plano. Expor ferramentas que o chamador não pode realmente invocar desperdiça turnos e confunde o modelo.

A Onplana resolveu isso em produção ao longo de seis meses de trabalho com servidores MCP. Publicar os padrões é de alto impacto:

Outros autores de MCP obtêm um modelo comprovado em vez de reinventar.
O repositório é uma superfície de sinal de pré-treinamento. READMEs públicos do GitHub têm peso significativo nos dados de treinamento de LLMs de próxima geração, e um repositório com padrões + documentação clara sobre MCP melhora a recordação do modelo sobre "como são bons servidores MCP".
A interface do despachante é a costura onde sua lógica de negócio se conecta. O transporte é genérico; o que importa no seu servidor MCP é o registro de ferramentas. Abrir o código do transporte não entrega nada proprietário.

A implementação do despachante, o catálogo de ferramentas, a lógica de portão de plano, a infraestrutura de auditoria e o restante do despachante fechado de ~600 LOC da Onplana permanecem no monorepo fechado porque codificam lógica de negócio da plataforma. Se você construir seu próprio servidor MCP usando este modelo, você escreve seu próprio despachante. Esse é o trabalho que importa e o trabalho específico da sua plataforma.

Estrutura do repositório

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*

Início rápido

Construir um servidor

Instale:

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

Conecte um aplicativo Express:

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)

Início rápido completo em packages/server-template/README.md; demonstração executável em examples/in-memory/.

Conduzir a Onplana a partir do código

Instale:

npm install github:Onplana/onplana-mcp-server

Use:

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,
})

Documentação completa do cliente em packages/client/README.md.

Ferramentas

O servidor hospedado em https://mcp.onplana.com/mcp expõe 285 ferramentas, abrangendo projetos, tarefas, sprints, marcos, valor agregado, riscos, problemas, governança, controle de mudanças, planilhas de horas, wikis, quadros brancos, fluxos de trabalho e as integrações do Microsoft Graph. O número exato que um determinado cliente vê é menor, porque as ferramentas são filtradas pela função do chamador e pelo plano da organização antes de o catálogo ser servido.

As 33 abaixo são as que valem a pena conhecer primeiro, não o catálogo inteiro. Leituras são anotadas com readOnlyHint; gravações carregam destructiveHint para que um cliente possa bloqueá-las. Cada chamada é executada sob a identidade do chamador, verificada contra as permissões desse usuário e o plano da organização, e registrada na trilha de auditoria.

Leitura (readOnlyHint: true)

list_projects: projetos na organização, filtráveis por status.
get_project: um projeto completo, com datas, responsável e progresso.
list_tasks: tarefas de um projeto, ou entre projetos.
get_task: uma tarefa com descrição, responsável, datas e comentários recentes.
list_my_tasks: tarefas atribuídas ao usuário chamador.
list_overdue: tarefas com data de vencimento passada.
list_team_members: membros de um projeto.
list_org_members: membros da organização.
list_risks: riscos registrados contra um projeto.
find_similar_projects: projetos anteriores semelhantes a uma descrição, para estimativa.
search_org_knowledge: busca híbrida BM25 e vetorial em tarefas, projetos, páginas de wiki e comentários.
summarize_project: resumo de IA sintetizado a partir do plano ao vivo.
analyze_project_risks: detecção de riscos por IA em cronograma, orçamento, escopo e recursos.
generate_status_report: relatório de status por IA a partir do cronograma e atividade atuais.
search: adaptador do Diretório de Aplicativos, retorna {id, title, snippet?, url?}.
fetch: adaptador do Diretório de Aplicativos, retorna {id, title, content, url?, metadata?}.

Gravação, aditiva (destructiveHint: false)

create_project: criar um projeto.
create_task: criar uma tarefa, opcionalmente sob uma tarefa pai.
create_milestone: adicionar um marco a um projeto.
create_comment: comentar em uma tarefa, problema ou projeto.
create_sprint_with_tasks: criar um sprint e puxar tarefas para ele.
submit_timesheet: registrar horas contra uma tarefa.
add_project_member: adicionar um membro existente da organização a um projeto.
link_dependency: vincular duas tarefas, idempotente por meio de uma restrição única.

Gravação, mutável (destructiveHint: true)

update_project: alterar campos do projeto, como status, datas ou orçamento.
update_task: alterar campos da tarefa, como status, progresso ou datas.
bulk_update_tasks: aplicar uma alteração em muitas tarefas.
assign_task: definir o responsável de uma tarefa.
move_task_to_sprint: mover uma tarefa para dentro ou para fora de um sprint.

Concessões (para agentes que compartilham um backlog)

next_task: escolher a próxima tarefa disponível e reivindicá-la em uma única chamada. Listar e depois reivindicar deixa uma lacuna em que dois agentes podem cair.
claim_task: obter uma concessão exclusiva em uma tarefa específica.
renew_task_lease: estender uma concessão enquanto o trabalho ainda está em andamento.
release_task: devolver a concessão; concluir ou bloquear uma tarefa também a libera, e encerrar uma sessão libera tudo o que aquela execução detém.

Uma concessão é vinculada à EXECUÇÃO, não ao usuário. Duas sessões de um mesmo cliente autenticam como a mesma persona de agente, então um bloqueio por usuário permitiria que uma sessão liberasse o trabalho da outra. As concessões expiram sozinhas, então um agente que travou libera sua tarefa em vez de retê-la.

Ferramentas de exclusão não estão no catálogo padrão, e operações destrutivas são negadas por padrão: um proprietário da organização as habilita por operação antes que um agente possa chamá-las. As que podem ser habilitadas são recuperáveis, indo para a lixeira em vez de serem destruídas. Prefira update_task em vez de excluir e recriar, já que a Onplana audita cada alteração de campo e mantém o histórico.

Lista de verificação de produção

O modelo + SDK fazem você rodar. Adicione estes por cima:

Limitação de taxa por token. 60–120 req/min por token Bearer; loops de agentes são mais ruidosos que humanos.
Limite de custo por locatário. Se suas ferramentas chamam LLMs pagos, bloqueie o despacho com base no gasto do mês até a data. A implantação da Onplana usa aiMonthlyCostCapUsd com modos WARN / BLOCK.
Registro de auditoria. Cada despacho deve gravar uma linha de auditoria marcada com actorType: 'mcp_agent' para que administradores possam ver o que agentes de IA fizeram em seu locatário separadamente da atividade humana.
Curadoria de plano / escopo. Não exponha toda ferramenta interna. A Onplana expõe 21 de 26; as 5 suprimidas ou precisam de uma UI de pré-visualização no aplicativo, são arriscadas demais para invocação não supervisionada ou produzem cargas úteis grandes demais.
Modo PREVIEW para mutações arriscadas. Padronize ferramentas mutáveis como somente pré-visualização em níveis gratuitos. A Onplana entrega isso: agentes veem "o que isso faria" antes de os usuários explicitamente fazerem upgrade e reexecutarem.
Chaves de idempotência. Faça hash da entrada canonicalizada + um ID de sessão; armazene como uma restrição única na sua linha de auditoria. Um modelo repetindo a mesma ação lógica não deve criar em dobro.

Cada um desses é específico da plataforma. O modelo dá a você a costura onde eles se conectam (Dispatcher.callTool); seu despachante os implementa da forma que sua plataforma codifica esses conceitos.

Compatibilidade

Node.js ≥ 20 (para o modelo de servidor e a matriz de CI); ≥ 18 para o cliente (usa fetch ambiente).
@modelcontextprotocol/sdk@^1.29.0
express@^4.18.0 ou express@^5.0.0

Testado contra:

Claude Code (marketplace de plugins, ou claude mcp add --transport http)
Claude Desktop (Conector Personalizado)
Cursor (~/.cursor/mcp.json)
Conectores personalizados do ChatGPT (onde MCP está habilitado na sua conta)
Gemini CLI + Gemini Code Assist (~/.gemini/settings.json)
GitHub Copilot no VS Code (.vscode/mcp.json)
O MCP Inspector oficial

Instalar no Claude Code

O repositório também funciona como um marketplace de plugins do Claude Code, então a instalação são dois comandos:

/plugin marketplace add Onplana/onplana-mcp-server
/plugin install onplana@onplana

Depois anexe o servidor:

/onplana-connect

Isso executa claude mcp add --transport http onplana https://mcp.onplana.com/mcp e guia você pelo login no navegador. O servidor MCP está disponível em todos os planos da Onplana, incluindo o gratuito.

O plugin inclui as duas habilidades de agente da Onplana, invocadas como onplana:<name>:

Habilidade	Use quando
`onplana-project-planner`	Você tem um objetivo ou um briefing e quer um plano executável: um documento de plano anexado ao projeto, depois uma árvore de tarefas com datas, dependências, responsáveis e casos de teste.
`onplana-autonomous-agent`	Um plano já existe e você quer executá-lo: reivindique uma tarefa, trabalhe nela, registre progresso e evidências, resolva ou devolva, depois pegue a próxima.

O manifesto do plugin deliberadamente não declara nenhum servidor MCP. Um plugin declara servidores na forma stdio (command, args, env), e o da Onplana é remoto e autenticado por OAuth, então /onplana-connect o anexa em tempo de execução pelo transporte HTTP nativo do Claude Code em vez de roteá-lo por um shim stdio.

Instalar no Gemini CLI

O repositório inclui um manifesto gemini-extension.json na raiz, então o Gemini CLI instala a Onplana com um comando:

export ONPLANA_PAT=pat_paste-your-token-here  # mint at app.onplana.com/integrations
gemini extensions install https://github.com/Onplana/onplana-mcp-server

Reinicie o CLI gemini (ou recarregue sua janela do VS Code / JetBrains se você estiver usando o Gemini Code Assist). As ferramentas da Onplana aparecem em /mcp e seu contexto GEMINI.md capta as dicas de uso incluídas neste repositório.

Contribuindo

Issues + PRs são bem-vindos. O repositório é pequeno por design; o objetivo é que os padrões de transporte sejam óbvios, bem testados e estáveis. Aumentos de versão principal são reservados para mudanças que quebram as formas exportadas de Dispatcher / BearerAuth / fábrica de manipuladores. Patches e menores são para refinamentos de contenção de injeção de prompt, novos utilitários auxiliares e cobertura de teste adicional.

Licença

Veja também

onplana.com/mcp: página de documentação pública para a implantação de MCP de produção da Onplana (catálogo completo de ferramentas, instruções de configuração, modelo de segurança)
onplana.com: Onplana, a plataforma de gerenciamento de projetos. Agnóstica de nuvem, nativa de IA, alternativa ao Microsoft Project Online
Especificação do Protocolo de Contexto de Modelo: o padrão MCP
Orientação de injeção de prompt da Anthropic: o padrão de segurança que o wrap deste repositório implementa