⭐️⭐️⭐️ Open-source, self-hosted alternative to Linear and Plane. Project management and issue tracking where teams and AI agents work side by side to plan and ship products.
TypeScript agenticagileai-agentsbug-reportingbug-trackerganttissue-trackerjirajira-alternativekanbanlinearlinear-alternativeopen-sourceproduct-managementproject-managementroadmapself-hostedsprint-planningteam-collaborationtrello-alternative
feat(api): manage internal agents fully over MCP (#59)
Croff6cb16bca2af3
diff --git a/apps/api/src/__tests__/helpers/mcp.ts b/apps/api/src/__tests__/helpers/mcp.tsnew file mode 100644index 00000000..30c8e9ea--- /dev/null+++ b/apps/api/src/__tests__/helpers/mcp.ts@@ -0,0 +1,13 @@+import { app } from '../../app';+import { routeTools } from '../../mcp/generate';++// The routes matching `match` that carry no MCP tool tag, as "METHOD /path". A route+// opts in with mcpTool() in its detail, so a feature's test pins which of its routes+// stay session-only.+export function untaggedRoutes(match: (route: string) => boolean): string[] {+ const tagged = new Set(routeTools(app).map((tool) => `${tool.method} ${tool.path}`));+ return app.routes+ .map((route) => `${route.method} ${route.path}`)+ .filter(match)+ .filter((route) => !tagged.has(route));+}diff --git a/apps/api/src/agent-skills/__tests__/integration/agent-skills.test.ts b/apps/api/src/agent-skills/__tests__/integration/agent-skills.test.tsindex c784a515..8d08d12b 100644--- a/apps/api/src/agent-skills/__tests__/integration/agent-skills.test.ts+++ b/apps/api/src/agent-skills/__tests__/integration/agent-skills.test.ts@@ -2,8 +2,7 @@ import { describe, it, expect, beforeEach } from 'bun:test';import { authedApi, type Api } from '../../../__tests__/helpers/app';import { signUpTestUser } from '../../../__tests__/helpers/auth';import { resetDb } from '../../../__tests__/helpers/db';-import { routeTools } from '../../../mcp/generate';-import { getMcpApp } from '../../../mcp/app-ref';+import { untaggedRoutes } from '../../../__tests__/helpers/mcp';// The project skill library: SKILL.md documents (plus optional reference files) given// to internal agents. Content lives in the object store; the row holds metadata.@@ -170,12 +169,9 @@ describe('agent skills', () => {// A skill library is managed over MCP, so every route here is tagged except the file// upload: an MCP call carries JSON, and uploading files is left to the UI.it('exposes every skill route to MCP', () => {- const app = getMcpApp();- const tagged = new Set(routeTools(app).map((tool) => `${tool.method} ${tool.path}`));- const untagged = app.routes- .map((route) => `${route.method} ${route.path}`)- .filter((route) => route.includes('agent-skills') || route.endsWith('/skills'))- .filter((route) => !tagged.has(route));+ const untagged = untaggedRoutes(+ (route) => route.includes('agent-skills') || route.endsWith('/skills'),+ );expect(untagged).toEqual(['POST /projects/:projectKey/agent-skills/:skillId/references']);});diff --git a/apps/api/src/agent-tools/__tests__/integration/agent-tools.test.ts b/apps/api/src/agent-tools/__tests__/integration/agent-tools.test.tsindex 0cbb4d1a..929d32cf 100644--- a/apps/api/src/agent-tools/__tests__/integration/agent-tools.test.ts+++ b/apps/api/src/agent-tools/__tests__/integration/agent-tools.test.ts@@ -2,6 +2,7 @@ import { describe, it, expect, beforeEach } from 'bun:test';import { authedApi, type Api } from '../../../__tests__/helpers/app';import { signUpTestUser } from '../../../__tests__/helpers/auth';import { resetDb } from '../../../__tests__/helpers/db';+import { untaggedRoutes } from '../../../__tests__/helpers/mcp';// Configured tools for a project: a catalog tool bound to an integration credential.// The secret lives on the credential, so a configured tool carries no secret. Access@@ -115,6 +116,18 @@ describe('agent tools', () => {expect(clear.data).toHaveLength(0);});+ // Over MCP a configured tool can be read and enabled on an agent, but binding one to+ // a credential stays in the UI, where the credential is added.+ it('exposes reading and enabling configured tools to MCP, not binding one', () => {+ const untagged = untaggedRoutes(+ (route) => route.includes('agent-tools') || route.includes('tool-configs'),+ );+ expect(untagged).toEqual([+ 'POST /projects/:projectKey/agent-tools',+ 'DELETE /projects/:projectKey/agent-tools/:agentToolId',+ ]);+ });+it('denies a non-member', async () => {await setup();const outsider = await signUpTestUser({ name: 'Outsider' });diff --git a/apps/api/src/agent-tools/routes.ts b/apps/api/src/agent-tools/routes.tsindex 0c1ab981..077a8f0d 100644--- a/apps/api/src/agent-tools/routes.ts+++ b/apps/api/src/agent-tools/routes.ts@@ -16,7 +16,10 @@ import {} from './store';const toolParams = t.Object({ projectKey: t.String(), agentToolId: t.Numeric() });-const agentParams = t.Object({ projectKey: t.String(), agentId: t.Numeric() });+const agentParams = t.Object({+ projectKey: t.String(),+ agentId: t.Numeric({ description: 'Agent id from list_ai_agents.' }),+});// A built-in agent action in the catalog (ToolMeta from ai-agents/runtime/tools).// `always` marks the read-only actions granted unconditionally, that cannot be@@ -43,10 +46,10 @@ const AgentToolResponse = t.Object({// Two tool systems live under this tag. Built-in agent actions (create_issue,// search_issues, ...) are the catalog an internal agent is granted through its-// `tools` field; the catalog route is read-only, ai_agents-gated, and exposed over-// MCP. Configured tools bind an external tool to an integration credential; those-// reference secrets, so they are session-only (not MCP tools) and gated under the-// agent_tools resource.+// `tools` field; the catalog route is read-only and ai_agents-gated. Configured tools+// bind an external tool to an integration credential and are gated under the+// agent_tools resource; binding one to a credential is done in the UI, so only reading+// them and enabling them on an agent are exposed over MCP.export const agentToolRoutes = new Elysia({name: 'agent-tools',detail: { tags: ['Agent Tools'] },@@ -83,7 +86,11 @@ export const agentToolRoutes = new Elysia({},detail: {summary: 'List configured tools',- description: "List a project's tools configured on integration credentials.",+ description:+ "List a project's tools configured on integration credentials. An id here is what " ++ 'set_ai_agent_configured_tools takes to enable a tool on an agent. Separate from the ' ++ 'built-in actions in list_ai_agent_tools.',+ ...mcpTool('list_configured_tools'),},})@@ -131,7 +138,6 @@ export const agentToolRoutes = new Elysia({},)- // Which configured tools are enabled on an agent..get('/projects/:projectKey/ai-agents/:agentId/tool-configs',async ({ params, project }) => {@@ -152,11 +158,11 @@ export const agentToolRoutes = new Elysia({detail: {summary: "List an agent's enabled tools",description: 'List the configured tools enabled on an agent.',+ ...mcpTool('list_ai_agent_configured_tools'),},},)- // Replaces the set of configured tools enabled on an agent..put('/projects/:projectKey/ai-agents/:agentId/tool-configs',async ({ params, project, body }) => {@@ -167,7 +173,11 @@ export const agentToolRoutes = new Elysia({return listAgentToolLinks(params.agentId);},{- body: t.Object({ agentToolIds: t.Array(t.Number()) }),+ body: t.Object({+ agentToolIds: t.Array(t.Number(), {+ description: 'Configured tool ids from list_configured_tools.',+ }),+ }),params: agentParams,permission: ['agent_tools', 'edit'],response: {@@ -179,7 +189,10 @@ export const agentToolRoutes = new Elysia({},detail: {summary: "Set an agent's enabled tools",- description: 'Replace the set of configured tools enabled on an agent.',+ description:+ 'Replace the set of configured tools enabled on an agent. Send the full set: a tool ' ++ 'left out is disabled.',+ ...mcpTool('set_ai_agent_configured_tools'),},},);diff --git a/apps/api/src/ai-agents/__tests__/integration/ai-agents.test.ts b/apps/api/src/ai-agents/__tests__/integration/ai-agents.test.tsindex 21cae913..04957c35 100644--- a/apps/api/src/ai-agents/__tests__/integration/ai-agents.test.ts+++ b/apps/api/src/ai-agents/__tests__/integration/ai-agents.test.ts@@ -2,6 +2,7 @@ import { describe, it, expect, beforeEach } from 'bun:test';import { authedApi, type Api } from '../../../__tests__/helpers/app';import { signUpTestUser } from '../../../__tests__/helpers/auth';import { resetDb } from '../../../__tests__/helpers/db';+import { untaggedRoutes } from '../../../__tests__/helpers/mcp';// AI agents attached to a project. Each agent is backed by a hidden bot user, owns a// better-auth API key, and is a project member acting under a project role. An@@ -364,4 +365,18 @@ describe('ai agents', () => {const res = await agents(asOwner)({ agentId: created.data!.agent.id }).run.post({ prompt: '' });expect(res.status).toBe(400);});++ // An agent is set up and talked to entirely over MCP. What stays out serves the chat+ // UI: the streamed run and the caller's own thread history, plus this agent's run+ // history — the analytics routes carry the project-wide run feed MCP reads instead.+ it('exposes agent management and the run to MCP', () => {+ const untagged = untaggedRoutes((route) => route.includes('/ai-agents'));+ expect(untagged).toEqual([+ 'GET /projects/:projectKey/ai-agents/:agentId/runs',+ 'POST /projects/:projectKey/ai-agents/:agentId/run/stream',+ 'GET /projects/:projectKey/ai-agents/:agentId/threads',+ 'GET /projects/:projectKey/ai-agents/:agentId/threads/:threadId/messages',+ 'DELETE /projects/:projectKey/ai-agents/:agentId/threads/:threadId',+ ]);+ });});diff --git a/apps/api/src/ai-agents/routes.ts b/apps/api/src/ai-agents/routes.tsindex 68fdbfe7..4e312bc5 100644--- a/apps/api/src/ai-agents/routes.ts+++ b/apps/api/src/ai-agents/routes.ts@@ -21,7 +21,10 @@ import { listAgentRuns } from './run-queue';import { listChatThreads, getChatThreadMessages, deleteChatThread } from './runtime/memory';import { isOwnChatThread } from './runtime/thread-ids';-const agentParams = t.Object({ projectKey: t.String(), agentId: t.Numeric() });+const agentParams = t.Object({+ projectKey: t.String(),+ agentId: t.Numeric({ description: 'Agent id from list_ai_agents.' }),+});const threadParams = t.Object({projectKey: t.String(),agentId: t.Numeric(),@@ -32,8 +35,10 @@ const threadParams = t.Object({// agent has memory enabled; omit it to start a new thread (the id used is returned in// the response).const runBody = t.Object({- prompt: t.String({ minLength: 1 }),- threadId: t.Optional(t.String()),+ prompt: t.String({ minLength: 1, description: 'Message to send the agent.' }),+ threadId: t.Optional(+ t.String({ description: 'Thread id from an earlier run, to continue that conversation.' }),+ ),});// Run options for an interactive chat run (the test chat): the caller owns the memory@@ -66,12 +71,29 @@ const username = t.String({// over time. Ignored (stored as null/empty) for an external agent.const configFields = {modelCredentialId: t.Optional(- t.Nullable(t.Number({ description: 'Integration credential id for the LLM provider.' })),+ t.Nullable(+ t.Number({+ description:+ 'Credential id of the LLM provider, from list_integration_credentials. Required for an ' ++ 'internal agent to run.',+ }),+ ),+ ),+ model: t.Optional(+ t.Nullable(+ t.String({+ description:+ "Model id the provider offers, from list_provider_models, e.g. 'claude-sonnet-5'.",+ }),+ ),),- model: t.Optional(t.Nullable(t.String({ description: 'Model id, e.g. claude-sonnet-5.' }))),instructions: t.Optional(t.Nullable(t.String({ description: 'System prompt for the agent.' }))),tools: t.Optional(- t.Array(t.String(), { description: 'Granted tool keys from list_ai_agent_tools.' }),+ t.Array(t.String(), {+ description:+ 'Built-in action keys from list_ai_agent_tools the agent is granted. Tools on an ' ++ 'integration are granted separately, through set_ai_agent_configured_tools.',+ }),),temperature: t.Optional(t.Nullable(t.Number({ description: 'Sampling temperature.' }))),maxSteps: t.Optional(t.Nullable(t.Integer({ description: 'Max tool-call steps per run.' }))),@@ -85,7 +107,11 @@ const configFields = {triggerOnAssign: t.Optional(t.Boolean({ description: 'Run when assigned to an issue.' })),roleId: t.Optional(t.Nullable(- t.Integer({ description: 'project_role the bot acts under; null uses the default role.' }),+ t.Integer({+ description:+ 'Role from list_roles the bot acts under, capping what its tools may do; null uses the ' ++ 'default role.',+ }),),),};@@ -378,9 +404,7 @@ export const aiAgentRoutes = new Elysia({ name: 'ai-agents', detail: { tags: ['A},)- // Runs an internal agent against a prompt and returns its generated text. The- // agent is built from its stored model configuration (Mastra). External agents- // have no config and return 400.+ // The agent is built from its stored model configuration (Mastra)..post('/projects/:projectKey/ai-agents/:agentId/run',async ({ params, project, body, user }) =>@@ -403,7 +427,9 @@ export const aiAgentRoutes = new Elysia({ name: 'ai-agents', detail: { tags: ['A},detail: {summary: 'Run an AI agent',- description: 'Run an internal AI agent with a prompt and return its text.',+ description:+ 'Send a prompt to an internal AI agent and return its answer. Only an internal agent ' ++ 'runs here; an external one has no model config and returns 400.',...mcpTool('run_ai_agent'),},},diff --git a/apps/api/src/integrations/__tests__/integration/integrations.test.ts b/apps/api/src/integrations/__tests__/integration/integrations.test.tsindex 836b9bf8..9825f64e 100644--- a/apps/api/src/integrations/__tests__/integration/integrations.test.ts+++ b/apps/api/src/integrations/__tests__/integration/integrations.test.ts@@ -2,6 +2,7 @@ import { describe, it, expect, beforeEach } from 'bun:test';import { authedApi, type Api } from '../../../__tests__/helpers/app';import { signUpTestUser } from '../../../__tests__/helpers/auth';import { resetDb } from '../../../__tests__/helpers/db';+import { untaggedRoutes } from '../../../__tests__/helpers/mcp';// Integration credentials for a project: one store for LLM provider keys (kind 'llm')// and tool credentials (kind 'tool'). The secret is stored encrypted and never@@ -121,6 +122,17 @@ describe('integrations', () => {expect((await integrations(asOwner).get()).data).toHaveLength(0);});+ // An agent's provider and model are picked over MCP, so the reads are tagged. The+ // writes are not: a credential body carries the provider's secret in plain text.+ it('exposes the credential reads to MCP, not the writes', () => {+ const untagged = untaggedRoutes((route) => route.includes('integrations'));+ expect(untagged).toEqual([+ 'POST /projects/:projectKey/integrations',+ 'PATCH /projects/:projectKey/integrations/:credentialId',+ 'DELETE /projects/:projectKey/integrations/:credentialId',+ ]);+ });+it('denies a non-member', async () => {await setup();const outsider = await signUpTestUser({ name: 'Outsider' });diff --git a/apps/api/src/integrations/routes.ts b/apps/api/src/integrations/routes.tsindex 2fe6d517..51b10f65 100644--- a/apps/api/src/integrations/routes.ts+++ b/apps/api/src/integrations/routes.ts@@ -4,6 +4,7 @@ import { guards } from '../shared/guards';import { authContext } from '../shared/auth-context';import { HttpError } from '../shared/lib';import { ErrorResponse } from '../shared/responses';+import { mcpTool } from '../mcp/generate';import { INTEGRATION_CATALOG } from './catalog';import { listModelsForProvider } from './models';import { listCredentials, createCredential, updateCredential, deleteCredential } from './store';@@ -46,8 +47,9 @@ const IntegrationResponse = t.Object({const ProviderModelResponse = t.Object({ id: t.String(), name: t.String() });-// Integration credentials carry secrets, so these routes are managed only through the-// session UI and are not exposed as MCP tools. Gated under the integrations resource.+// Gated under the integrations resource. The reads are exposed as MCP tools, so an+// internal agent's provider and model can be picked without the UI; the writes are+// not, because a credential body carries the provider's secret in plain text.export const integrationRoutes = new Elysia({name: 'integrations',detail: { tags: ['Integrations'] },@@ -55,8 +57,7 @@ export const integrationRoutes = new Elysia({.use(authContext).use(guards)- // The catalog of integrations (LLM providers + tool integrations). The frontend- // builds the credential form from credentialSchema.+ // The frontend builds the credential form from credentialSchema..get('/projects/:projectKey/integrations/catalog', () => INTEGRATION_CATALOG, {permission: ['integrations', 'read'],response: {@@ -67,17 +68,25 @@ export const integrationRoutes = new Elysia({},detail: {summary: 'List available integrations',- description: 'List the integration catalog: LLM providers and tool integrations.',+ description:+ "List the integration catalog: LLM providers (kind 'llm') and tool integrations " ++ "(kind 'tool'). A provider key here is what list_provider_models takes.",+ ...mcpTool('list_integrations'),},})// The models an LLM provider offers, from the models.dev registry. Backs the model- // select in the agent config UI. Empty when the registry is unavailable.+ // select in the agent config UI..get('/projects/:projectKey/integrations/models/:provider',({ params }) => listModelsForProvider(params.provider),{- params: t.Object({ projectKey: t.String(), provider: t.String() }),+ params: t.Object({+ projectKey: t.String(),+ provider: t.String({+ description: "LLM provider key from list_integrations, e.g. 'anthropic'.",+ }),+ }),permission: ['integrations', 'read'],response: {200: t.Array(ProviderModelResponse),@@ -87,7 +96,11 @@ export const integrationRoutes = new Elysia({},detail: {summary: "List a provider's models",- description: 'List the models an LLM provider offers.',+ description:+ 'List the models an LLM provider offers. An id here is what the model field on ' ++ 'create_ai_agent / update_ai_agent takes. Empty when the model registry is unreachable.',+ // The list comes from models.dev, the one route here that reads outside the tracker.+ ...mcpTool('list_provider_models', { openWorldHint: true }),},},)@@ -102,7 +115,11 @@ export const integrationRoutes = new Elysia({},detail: {summary: 'List credentials',- description: "List a project's integration credentials (secrets redacted).",+ description:+ "List a project's integration credentials, secrets redacted. The id of a credential " ++ 'on an LLM provider is what modelCredentialId on create_ai_agent / update_ai_agent takes. ' ++ 'A credential is added in the UI, not here.',+ ...mcpTool('list_integration_credentials'),},})