outline-mcp-server 4.12.2 → 5.0.0

package/README.md

@@ -2,6 +2,12 @@
 
 A Model Context Protocol (MCP) server that provides tools for interacting with [Outline](https://www.getoutline.com/)'s API, enabling AI agents to manage documents, collections, and other entities programmatically through the Outline knowledge base platform.
 
+> **Upgrade Notice:**
+
+- v5 has introduced several breaking changes:
+  - this server support for both `stdio` and `sse` transport interfaces. It now solely exposes a [Streamable HTTP endpoint](https://modelcontextprotocol.io/specification/draft/basic/transports#streamable-http) at the `/mcp` route. If you require sse/stdio, downgrade to v4
+  - the `--port` CLI flag has been migrated to an environment variable, `OUTLINE_MCP_PORT`
+
 ## Features
 
 - **Document Management**
@@ -32,38 +38,31 @@ A Model Context Protocol (MCP) server that provides tools for interacting with [
 - **User Management**
   - ✅ List and filter users
 
-> **Note:** The SSE server implementation uses [Supergateway](https://github.com/supercorp-ai/supergateway), which provides more reliable connectivity when used with Cursor's MCP integration.
-
 ## Quick Start
 
 ### Prerequisites
 
-- Node.js (v18 or higher)
-- An Outline account with API access
+- Node.js (v20 or higher)
+- Outline account with API access
 - Outline API key with appropriate permissions
+- Note: if you need to use the AI-powered ask feature, you must enable the "AI Answers" feature in your Outline Workspace settings
 
 ### Installation
 
 ```bash
-# Run directly with npx
-OUTLINE_API_KEY=… npx outline-mcp-server
+# (preferred) Run directly with npx
+OUTLINE_API_KEY=... npx outline-mcp-server
 
 # or install from npm
 npm install -g outline-mcp-server
-OUTLINE_API_KEY=… outline-mcp-server
-
-# Run with a custom port (default is 6060)
-OUTLINE_API_KEY=… outline-mcp-server --port 7070
+OUTLINE_API_KEY=... outline-mcp-server
 ```
 
 ### Env
 
 - `OUTLINE_API_KEY` (_required_): your API key for outline, duh
-- `OUTLINE_BASE_URL` (_optional_): Alternative URL for your outline API (if using an alt domain/self-hosting)
-
-### CLI Options
-
-- `--port <number>` (_optional_): Specify the port on which the server will run (default: 6060)
+- `OUTLINE_API_URL` (_optional_): Alternative URL for your outline API (if using an alt domain/self-hosting)
+- `OUTLINE_MCP_PORT` (_optional_): Specify the port on which the server will run (default: 6060)
 
 ### Usage
 
@@ -79,6 +78,16 @@ Example queries your AI assistant can now handle:
 - "Update the content of a document"
 - "Add a comment to a document"
 
+### Run the MCP server
+
+```bash
+# Default port 6060
+OUTLINE_API_KEY=... npm run start:http
+
+# Or specify a custom port
+OUTLINE_API_KEY=... OUTLINE_MCP_PORT=9001 npm run start:http
+```
+
 ## Development
 
 ```bash
@@ -94,13 +103,15 @@ npm install
 
 ```
 OUTLINE_API_KEY=your_outline_api_key_here
-OUTLINE_BASE_URL=https://your-outline-instance.com/api  # Optional, defaults to https://app.getoutline.com/api
+
+# Optional -------
+# OUTLINE_API_URL=https://your-outline-instance.com/api # defaults to https://app.getoutline.com/api
+# OUTLINE_MCP_PORT=9001
 ```
 
 ```bash
 # Builds/watches the project alongside running @modelcontextprotocol/inspector
 npm run dev
-
 ```
 
 ## Contributing

package/build/index.js

@@ -1,58 +1,59 @@
-#!/usr/bin/env node
-import { Server } from '@modelcontextprotocol/sdk/server/index.js';
-import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import { CallToolRequestSchema, ErrorCode, ListToolsRequestSchema, McpError, } from '@modelcontextprotocol/sdk/types.js';
-import { registerTools } from './utils/importTools.js';
-import { omit } from 'omit-ts';
-// Dynamically import all tool files
-const toolDefinitions = await registerTools();
-console.log('\n', `loaded ${Object.keys(toolDefinitions).length} tools`, JSON.stringify(Object.keys(toolDefinitions)), '\n');
-const server = new Server({
-    name: 'outline-mcp',
-    version: '1.0.0',
-}, {
-    capabilities: {
-        tools: Object.entries(toolDefinitions).reduce((acc, [name, definition]) => {
-            acc[name] = true;
-            return acc;
-        }, {}),
-    },
-});
-// Register request handlers
-server.setRequestHandler(ListToolsRequestSchema, async () => ({
-    tools: Object.values(toolDefinitions).map(x => omit(x, ['handler'])),
-}));
-server.setRequestHandler(CallToolRequestSchema, async (request) => {
-    const { params } = request;
-    const toolName = params.name;
-    const parameters = params.arguments || {};
-    const toolDefinition = toolDefinitions[toolName];
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import fastify from 'fastify';
+import { getMcpServer } from './utils/getMcpServer.js';
+const server = fastify();
+// Stateless mode (default, recommended for most deployments)
+server.post('/mcp', async (request, reply) => {
     try {
-        // Check if the tool is supported
-        if (!toolDefinition) {
-            return {
-                error: { code: ErrorCode.InvalidRequest, message: `Tool ${toolName} not supported` },
-            };
-        }
-        // Call the handler with the provided parameters
-        const result = await toolDefinition.handler(parameters);
-        return {
-            content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
-        };
+        const mcpServer = await getMcpServer();
+        const httpTransport = new StreamableHTTPServerTransport({
+            sessionIdGenerator: undefined,
+        });
+        reply.raw.on('close', () => {
+            httpTransport.close();
+            mcpServer.close();
+        });
+        await mcpServer.connect(httpTransport);
+        await httpTransport.handleRequest(request.raw, reply.raw, request.body);
     }
     catch (error) {
-        if (error instanceof McpError) {
-            return { error: { code: error.code, message: error.message } };
+        if (!reply.sent) {
+            reply.code(500).send({
+                jsonrpc: '2.0',
+                error: {
+                    code: -32603,
+                    message: 'Internal server error',
+                },
+                id: null,
+            });
         }
-        return { error: { code: ErrorCode.InternalError, message: error.message } };
     }
 });
-async function main() {
-    const transport = new StdioServerTransport();
-    await server.connect(transport);
-    console.log('Outline MCP server running on stdio');
-}
-main().catch(error => {
-    console.error('Server error:', error);
-    process.exit(1);
+server.get('/mcp', async (request, reply) => {
+    reply.code(405).send({
+        jsonrpc: '2.0',
+        error: {
+            code: -32000,
+            message: 'Method not allowed.',
+        },
+        id: null,
+    });
+});
+server.delete('/mcp', async (request, reply) => {
+    reply.code(405).send({
+        jsonrpc: '2.0',
+        error: {
+            code: -32000,
+            message: 'Method not allowed.',
+        },
+        id: null,
+    });
+});
+const PORT = process.env.OUTLINE_MCP_PORT ? parseInt(process.env.OUTLINE_MCP_PORT, 10) : 6060;
+server.listen({ port: PORT }, (err, address) => {
+    if (err) {
+        console.error(err);
+        process.exit(1);
+    }
+    console.log(`Outline MCP Server (streamable-http) running at ${address}/mcp`);
 });

package/build/tools/archiveDocument.js

@@ -1,26 +1,20 @@
 import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
-import { outlineClient } from '../client.js';
-import { registerTool } from '../utils/listTools.js';
+import { outlineClient } from '../outline/outlineClient.js';
+import toolRegistry from '../utils/toolRegistry.js';
+import { z } from 'zod';
 // Register this tool
-registerTool({
+toolRegistry.register('archive-document', {
     name: 'archive_document',
     description: 'Archive a document',
     inputSchema: {
-        properties: {
-            id: {
-                type: 'string',
-                description: 'ID of the document to archive',
-            },
-        },
-        required: ['id'],
-        type: 'object',
+        id: z.string().describe('ID of the document to archive'),
     },
-    handler: async function handleArchiveDocument(args) {
+    async callback(args) {
         try {
             const response = await outlineClient.post('/documents.archive', {
                 id: args.id,
             });
-            return response.data.data;
+            return { content: [{ type: 'text', text: JSON.stringify(response.data.data) }] };
         }
         catch (error) {
             console.error('Error archiving document:', error.message);

package/build/tools/askDocuments.js

@@ -1,43 +1,29 @@
 import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
-import { outlineClient } from '../client.js';
-import { registerTool } from '../utils/listTools.js';
+import { outlineClient } from '../outline/outlineClient.js';
+import toolRegistry from '../utils/toolRegistry.js';
+import z from 'zod';
 // Register this tool
-registerTool({
+toolRegistry.register('ask_documents', {
     name: 'ask_documents',
     description: 'Query documents with natural language. This method allows asking direct questions of your documents - where possible an answer will be provided. Search results will be restricted to those accessible by the current access token. Note that "AI answers" must be enabled for the workspace.',
     inputSchema: {
-        properties: {
-            query: {
-                type: 'string',
-                description: 'The natural language query to ask about your documents',
-            },
-            userId: {
-                type: 'string',
-                description: 'Any documents that have not been edited by the user identifier will be filtered out',
-            },
-            collectionId: {
-                type: 'string',
-                description: 'A collection to search within',
-            },
-            documentId: {
-                type: 'string',
-                description: 'A document to search within',
-            },
-            statusFilter: {
-                type: 'string',
-                enum: ['draft', 'archived', 'published'],
-                description: 'Any documents that are not in the specified status will be filtered out',
-            },
-            dateFilter: {
-                type: 'string',
-                enum: ['day', 'week', 'month', 'year'],
-                description: 'Any documents that have not been updated within the specified period will be filtered out',
-            },
-        },
-        required: ['query'],
-        type: 'object',
+        query: z.string().describe('The natural language query to ask about your documents'),
+        userId: z
+            .string()
+            .describe('Any documents that have not been edited by the user identifier will be filtered out')
+            .optional(),
+        collectionId: z.string().describe('A collection to search within').optional(),
+        documentId: z.string().describe('A document to search within').optional(),
+        statusFilter: z
+            .enum(['draft', 'archived', 'published'])
+            .describe('Any documents that are not in the specified status will be filtered out')
+            .optional(),
+        dateFilter: z
+            .enum(['day', 'week', 'month', 'year'])
+            .describe('Any documents that have not been updated within the specified period will be filtered out')
+            .optional(),
     },
-    handler: async function handleAskDocuments(args) {
+    async callback(args) {
         try {
             const payload = {
                 query: args.query,
@@ -58,7 +44,7 @@ registerTool({
                 payload.dateFilter = args.dateFilter;
             }
             const response = await outlineClient.post('/documents.answerQuestion', payload);
-            return response.data;
+            return { content: [{ type: 'text', text: JSON.stringify(response.data.data) }] };
         }
         catch (error) {
             console.error('Error asking documents:', error.message);

package/build/tools/createCollection.js

@@ -1,37 +1,22 @@
 import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
-import { outlineClient } from '../client.js';
-import { registerTool } from '../utils/listTools.js';
+import { outlineClient } from '../outline/outlineClient.js';
+import toolRegistry from '../utils/toolRegistry.js';
+import z from 'zod';
 // Register this tool
-registerTool({
+toolRegistry.register('create_collection', {
     name: 'create_collection',
     description: 'Create a new collection',
     inputSchema: {
-        properties: {
-            name: {
-                type: 'string',
-                description: 'Title of the collection',
-            },
-            description: {
-                type: 'string',
-                description: 'Content of the collection in markdown format',
-            },
-            permission: {
-                type: 'string',
-                description: 'Permission level for the collection (read, read_write)',
-            },
-            color: {
-                type: 'string',
-                description: 'Hex color code for the collection',
-            },
-            private: {
-                type: 'boolean',
-                description: 'Whether this collection is private',
-            },
-        },
-        required: ['name'],
-        type: 'object',
+        name: z.string().describe('Title of the collection'),
+        description: z.string().describe('Content of the collection in markdown format').optional(),
+        permission: z
+            .enum(['read', 'read_write'])
+            .describe('Permission level for the collection')
+            .optional(),
+        color: z.string().describe('Hex color code for the collection').optional(),
+        private: z.boolean().describe('Whether this collection is private').optional(),
     },
-    handler: async function handleCreateCollection(args) {
+    async callback(args) {
         try {
             const payload = {
                 name: args.name,
@@ -49,7 +34,7 @@ registerTool({
                 payload.private = args.private;
             }
             const response = await outlineClient.post('/collections.create', payload);
-            return response.data.data;
+            return { content: [{ type: 'text', text: JSON.stringify(response.data.data) }] };
         }
         catch (error) {
             console.error('Error creating collection:', error.message);

package/build/tools/createComment.js

@@ -1,33 +1,21 @@
 import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
-import { outlineClient } from '../client.js';
-import { registerTool } from '../utils/listTools.js';
+import { outlineClient } from '../outline/outlineClient.js';
+import toolRegistry from '../utils/toolRegistry.js';
+import z from 'zod';
 // Register this tool
-registerTool({
+toolRegistry.register('create_comment', {
     name: 'create_comment',
     description: 'Create a new comment on a document',
     inputSchema: {
-        properties: {
-            documentId: {
-                type: 'string',
-                description: 'ID of the document to comment on',
-            },
-            text: {
-                type: 'string',
-                description: 'Content of the comment in markdown format',
-            },
-            parentCommentId: {
-                type: 'string',
-                description: 'ID of the parent comment (if replying to a comment)',
-            },
-            data: {
-                type: 'object',
-                description: 'Additional data for the comment (optional)',
-            },
-        },
-        required: ['documentId', 'text'],
-        type: 'object',
+        documentId: z.string().describe('ID of the document to comment on'),
+        text: z.string().describe('Content of the comment in markdown format'),
+        parentCommentId: z
+            .string()
+            .describe('ID of the parent comment (if replying to a comment)')
+            .optional(),
+        data: z.object({}).describe('Additional data for the comment (optional)').optional(),
     },
-    handler: async function handleCreateComment(args) {
+    async callback(args) {
         try {
             const payload = {
                 documentId: args.documentId,
@@ -40,7 +28,7 @@ registerTool({
                 payload.data = args.data;
             }
             const response = await outlineClient.post('/comments.create', payload);
-            return response.data.data;
+            return { content: [{ type: 'text', text: JSON.stringify(response.data.data) }] };
         }
         catch (error) {
             console.error('Error creating comment:', error.message);

package/build/tools/createDocument.js

@@ -1,42 +1,23 @@
 import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
-import { outlineClient } from '../client.js';
-import { registerTool } from '../utils/listTools.js';
+import { outlineClient } from '../outline/outlineClient.js';
+import toolRegistry from '../utils/toolRegistry.js';
+import z from 'zod';
 // Register this tool
-registerTool({
+toolRegistry.register('create_document', {
     name: 'create_document',
     description: 'Create a new document',
     inputSchema: {
-        properties: {
-            title: {
-                type: 'string',
-                description: 'Title of the document',
-            },
-            text: {
-                type: 'string',
-                description: 'Content of the document in markdown format',
-            },
-            collectionId: {
-                type: 'string',
-                description: 'ID of the collection to add the document to',
-            },
-            parentDocumentId: {
-                type: 'string',
-                description: 'ID of the parent document (if creating a nested document)',
-            },
-            publish: {
-                type: 'boolean',
-                default: true,
-                description: 'Whether to publish the document immediately',
-            },
-            template: {
-                type: 'boolean',
-                description: 'Whether this document is a template',
-            },
-        },
-        required: ['title', 'text', 'collectionId'],
-        type: 'object',
+        title: z.string().describe('Title of the document'),
+        text: z.string().describe('Content of the document in markdown format'),
+        collectionId: z.string().describe('ID of the collection to add the document to'),
+        parentDocumentId: z
+            .string()
+            .describe('ID of the parent document (if creating a nested document)')
+            .optional(),
+        publish: z.boolean().describe('Whether to publish the document immediately').optional(),
+        template: z.boolean().describe('Whether this document is a template').optional(),
     },
-    handler: async function handleCreateDocument(args) {
+    async callback(args) {
         try {
             const payload = {
                 title: args.title,
@@ -53,7 +34,7 @@ registerTool({
                 payload.template = args.template;
             }
             const response = await outlineClient.post('/documents', payload);
-            return response.data.data;
+            return { content: [{ type: 'text', text: JSON.stringify(response.data.data) }] };
         }
         catch (error) {
             console.error('Error creating document:', error.message);

package/build/tools/createTemplateFromDocument.js

@@ -1,27 +1,21 @@
 import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
-import { outlineClient } from '../client.js';
-import { registerTool } from '../utils/listTools.js';
+import { outlineClient } from '../outline/outlineClient.js';
+import toolRegistry from '../utils/toolRegistry.js';
+import z from 'zod';
 // Register this tool
-registerTool({
+toolRegistry.register('create_template_from_document', {
     name: 'create_template_from_document',
     description: 'Create a template from an existing document. This method allows you to create a new template using an existing document as the basis.',
     inputSchema: {
-        properties: {
-            id: {
-                type: 'string',
-                description: 'The ID of the document to use as a basis for the template',
-            },
-        },
-        required: ['id'],
-        type: 'object',
+        id: z.string().describe('The ID of the document to use as a basis for the template'),
     },
-    handler: async function handleCreateTemplateFromDocument(args) {
+    async callback(args) {
         try {
             const payload = {
                 id: args.id,
             };
             const response = await outlineClient.post('/documents.templatize', payload);
-            return response.data.data;
+            return { content: [{ type: 'text', text: JSON.stringify(response.data.data) }] };
         }
         catch (error) {
             console.error('Error creating template from document:', error.message);

package/build/tools/deleteComment.js

@@ -1,26 +1,20 @@
 import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
-import { outlineClient } from '../client.js';
-import { registerTool } from '../utils/listTools.js';
+import { outlineClient } from '../outline/outlineClient.js';
+import toolRegistry from '../utils/toolRegistry.js';
+import z from 'zod';
 // Register this tool
-registerTool({
+toolRegistry.register('delete_comment', {
     name: 'delete_comment',
     description: 'Delete a comment from a document',
     inputSchema: {
-        properties: {
-            id: {
-                type: 'string',
-                description: 'ID of the comment to delete',
-            },
-        },
-        required: ['id'],
-        type: 'object',
+        id: z.string().describe('ID of the comment to delete'),
     },
-    handler: async function handleDeleteComment(args) {
+    async callback(args) {
         try {
             const response = await outlineClient.post('/comments.delete', {
                 id: args.id,
             });
-            return response.data.success;
+            return { content: [{ type: 'text', text: JSON.stringify(response.data.success) }] };
         }
         catch (error) {
             console.error('Error deleting comment:', error.message);

package/build/tools/deleteDocument.js

@@ -1,26 +1,20 @@
 import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
-import { outlineClient } from '../client.js';
-import { registerTool } from '../utils/listTools.js';
+import { outlineClient } from '../outline/outlineClient.js';
+import toolRegistry from '../utils/toolRegistry.js';
+import z from 'zod';
 // Register this tool
-registerTool({
+toolRegistry.register('delete_document', {
     name: 'delete_document',
     description: 'Delete a document',
     inputSchema: {
-        properties: {
-            id: {
-                type: 'string',
-                description: 'ID of the document to delete',
-            },
-        },
-        required: ['id'],
-        type: 'object',
+        id: z.string().describe('ID of the document to delete'),
     },
-    handler: async function handleDeleteDocument(args) {
+    async callback(args) {
         try {
             const response = await outlineClient.post('/documents.delete', {
                 id: args.id,
             });
-            return response.data.success;
+            return { content: [{ type: 'text', text: JSON.stringify(response.data.success) }] };
         }
         catch (error) {
             console.error('Error deleting document:', error.message);

package/build/tools/getCollection.js

@@ -1,24 +1,18 @@
 import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
-import { outlineClient } from '../client.js';
-import { registerTool } from '../utils/listTools.js';
+import { outlineClient } from '../outline/outlineClient.js';
+import toolRegistry from '../utils/toolRegistry.js';
+import z from 'zod';
 // Register this tool
-registerTool({
+toolRegistry.register('get_collection', {
     name: 'get_collection',
     description: 'Get details about a specific collection',
     inputSchema: {
-        properties: {
-            id: {
-                type: 'string',
-                description: 'ID of the collection to retrieve',
-            },
-        },
-        required: ['id'],
-        type: 'object',
+        id: z.string().describe('ID of the collection to retrieve'),
     },
-    handler: async function handleGetCollection(args) {
+    async callback(args) {
         try {
             const response = await outlineClient.post(`/collections.info`, { id: args.id });
-            return response.data.data;
+            return { content: [{ type: 'text', text: JSON.stringify(response.data.data) }] };
         }
         catch (error) {
             console.error('Error getting collection:', error.message);