⭐️⭐️⭐️ 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
import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
import { agentTeam } from '#modules/agents/core/service';
import { listTeams } from '#modules/teams/service';
import type { McpApp } from './types';
import { routeTools, withoutFields, type McpRouteTool, type ViewedAttachments } from './generate';
import { dispatchTool } from './dispatch';
import { SERVER_INSTRUCTIONS } from './instructions';
import type { McpCredential } from './credential';
import { toolError } from './result';
// The path param of every team-scoped route.
const TEAM_PARAM = 'teamId';
// The team the caller's tool calls act in, or null when they have to name one.
//
// A client knows projects, not teams, so the team is resolved from the key rather
// than asked for: an agent key acts in the team its agent belongs to, and a person
// with a single team acts in that one. A person in several teams names the team on
// each call. It is never resolved from projectKey — an agent has to be creatable in
// a team that holds no project.
async function callerTeam(userId: string): Promise<number | null> {
const ofAgent = await agentTeam(userId);
if (ofAgent !== null) return ofAgent;
const teams = await listTeams(userId, { mcpOnly: true });
return teams.length === 1 ? teams[0].id : null;
}
// A low-level MCP Server for one request. tools/list returns every route tagged
// with x-mcp; tools/call dispatches to the real route via app.handle with the
// caller's API key. The low-level Server (not McpServer) is used so the route's
// TypeBox JSON Schema can be served as the tool inputSchema without converting to
// Zod. Arguments are validated by the route itself, not here.
export async function buildMcpServer(
app: McpApp,
credential: McpCredential,
userId: string,
clientRequest?: Request,
): Promise<Server> {
const server = new Server(
// `name` is the stable programmatic identifier; `title` is the human-readable
// display name a client shows to the user (per the MCP Implementation spec).
{ name: 'itsaplan', title: 'Itsaplan', version: '1.0.0' },
// `instructions` reaches the client in the initialize response and covers what
// no single tool description can: which tool resolves ids, how a column is
// picked, how far a request to "work on an issue" goes.
{ capabilities: { tools: {} }, instructions: SERVER_INSTRUCTIONS },
);
const table = routeTools(app);
const byName = new Map(table.map((t) => [t.name, t]));
const teamId = await callerTeam(userId);
const needsTeam = (tool: McpRouteTool) => tool.pathParams.includes(TEAM_PARAM);
server.setRequestHandler(ListToolsRequestSchema, async () => ({
tools: table.map((t) => ({
name: t.name,
description: t.description,
// A caller whose team is already known does not get to name one.
inputSchema:
teamId !== null && needsTeam(t)
? withoutFields(t.inputSchema, [TEAM_PARAM])
: t.inputSchema,
annotations: t.annotations,
outputSchema: t.images ? undefined : t.outputSchema,
})),
}));
server.setRequestHandler(CallToolRequestSchema, async (req) => {
const tool = byName.get(req.params.name);
if (!tool) {
const text = `Unknown tool: ${req.params.name}`;
return {
content: [{ type: 'text', text }],
isError: true,
structuredContent: toolError(404, text),
};
}
const args = { ...(req.params.arguments ?? {}) };
if (needsTeam(tool)) {
if (teamId !== null) args[TEAM_PARAM] = teamId;
else if (args[TEAM_PARAM] == null) {
const text =
'teamId is required: no single team follows from your key. Call list_teams and ' +
'pass the id of the team to act in.';
return {
content: [{ type: 'text', text }],
isError: true,
structuredContent: toolError(400, text),
};
}
}
const { text, isError, structuredContent } = await dispatchTool(app, tool, args, credential, {
viaMcpEndpoint: true,
clientRequest,
});
if (tool.images && !isError) return { content: imageContent(text) };
return { content: [{ type: 'text', text }], isError, structuredContent };
});
return server;
}
// The images of an image tool follow a text block that names them in the same order and
// lists the attachments left out. There is no structuredContent (nor an outputSchema to
// require one): Claude Code gives the model structuredContent in place of the text
// block when it is present, and earlier versions dropped the images as well.
function imageContent(text: string) {
const { images, others } = JSON.parse(text) as ViewedAttachments;
const named = images.map(({ id, filename, contentType }) => ({ id, filename, contentType }));
return [
{ type: 'text' as const, text: JSON.stringify({ images: named, others }) },
...images.map((image) => ({
type: 'image' as const,
data: image.data,
mimeType: image.contentType,
})),
];
}