outline-mcp-server 5.0.1 → 5.2.0

package/README.md

@@ -1,12 +1,16 @@
 # Outline MCP Server
 
+[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/install-mcp?name=outline&config=eyJjb21tYW5kIjoibnB4IC15IG91dGxpbmUtbWNwLXNlcnZlci1zdGRpb0BsYXRlc3QiLCJlbnYiOnsiT1VUTElORV9BUElfS0VZIjoiPFJFUExBQ0VfTUU%2BIiwiT1VUTElORV9BUElfVVJMIjoiaHR0cHM6Ly9hcHAuZ2V0b3V0bGluZS5jb20vYXBpIiwiT1VUTElORV9NQ1BfUE9SVCI6IjYwNjAifX0%3D)
+
+![npm](https://img.shields.io/npm/v/outline-mcp-server) • ![downloads](https://img.shields.io/npm/dy/outline-mcp-server)
+
 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:**
+## 🚨 \***\*Upgrade Notice:\*\*** v5 has introduced several breaking changes: 🚨
 
-- 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`
+- the `--port` CLI flag has been migrated to an environment variable, `OUTLINE_MCP_PORT`
+- Minimum node version has been bumped to 20
+- sse & stdio were removed in 5.0.0 but later re-introduced in 5.1.0 and 5.2.0 respectively
 
 ## Features
 
@@ -47,18 +51,35 @@ A Model Context Protocol (MCP) server that provides tools for interacting with [
 - 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
+### Running directly
 
 ```bash
-# (preferred) Run directly with npx
-OUTLINE_API_KEY=... npx outline-mcp-server
+# S-HTTP/SSE servers
+OUTLINE_API_KEY=... npx outline-mcp-server@latest -y
 
-# or install from npm
-npm install -g outline-mcp-server
-OUTLINE_API_KEY=... outline-mcp-server
+# STDIO
+OUTLINE_API_KEY=... npx outline-mcp-server-stdio@latest -y
 ```
 
-### Env
+### Cursor (mcp.json)
+
+Add the following MCP definition to your configuration:
+
+```json
+{
+  "outline": {
+    "command": "npx",
+    "args": ["-y", "outline-mcp-server-stdio@latest"],
+    "env": {
+      "OUTLINE_API_KEY": "<REPLACE_ME>",
+      "OUTLINE_API_URL": "https://app.getoutline.com/api",
+      "OUTLINE_MCP_PORT": "6060"
+    }
+  }
+}
+```
+
+### Env vars
 
 - `OUTLINE_API_KEY` (_required_): your API key for outline, duh
 - `OUTLINE_API_URL` (_optional_): Alternative URL for your outline API (if using an alt domain/self-hosting)
@@ -78,16 +99,6 @@ 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

package/build/index.js

@@ -1,12 +1,14 @@
 #!/usr/bin/env bun
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js';
 import fastify from 'fastify';
 import { getMcpServer } from './utils/getMcpServer.js';
-const server = fastify();
+const mcpServer = await getMcpServer();
+// HTTP mode - default behavior
+const app = fastify();
 // Stateless mode (default, recommended for most deployments)
-server.post('/mcp', async (request, reply) => {
+app.post('/mcp', async (request, reply) => {
     try {
-        const mcpServer = await getMcpServer();
         const httpTransport = new StreamableHTTPServerTransport({
             sessionIdGenerator: undefined,
         });
@@ -30,7 +32,7 @@ server.post('/mcp', async (request, reply) => {
         }
     }
 });
-server.get('/mcp', async (request, reply) => {
+app.get('/mcp', async (request, reply) => {
     reply.code(405).send({
         jsonrpc: '2.0',
         error: {
@@ -40,7 +42,7 @@ server.get('/mcp', async (request, reply) => {
         id: null,
     });
 });
-server.delete('/mcp', async (request, reply) => {
+app.delete('/mcp', async (request, reply) => {
     reply.code(405).send({
         jsonrpc: '2.0',
         error: {
@@ -50,11 +52,44 @@ server.delete('/mcp', async (request, reply) => {
         id: null,
     });
 });
+// Legacy SSE endpoint for older clients
+let sseTransport = null;
+app.get('/sse', async (request, reply) => {
+    try {
+        // Create SSE transport for legacy clients
+        if (!sseTransport) {
+            sseTransport = new SSEServerTransport('/messages', reply.raw);
+            await mcpServer.connect(sseTransport);
+        }
+    }
+    catch (error) {
+        console.error(error);
+        if (!reply.sent) {
+            reply.code(500).send({
+                jsonrpc: '2.0',
+                error: {
+                    code: -32603,
+                    message: 'Internal server error',
+                },
+                id: null,
+            });
+        }
+    }
+});
+// Legacy message endpoint for older clients
+app.post('/messages', async (req, res) => {
+    if (!sseTransport) {
+        res.status(400).send('No transport found');
+        return;
+    }
+    await sseTransport.handlePostMessage(req.raw, res.raw, req.body);
+});
 const PORT = process.env.OUTLINE_MCP_PORT ? parseInt(process.env.OUTLINE_MCP_PORT, 10) : 6060;
-server.listen({ port: PORT }, (err, address) => {
+app.listen({ port: PORT }, (err, address) => {
     if (err) {
         console.error(err);
         process.exit(1);
     }
-    console.log(`Outline MCP Server (streamable-http) running at ${address}/mcp`);
+    console.log(`\n\nOutline MCP Server running:\n\tstreamable-http: ${address}/mcp\n\tsse (deprecated): ${address}/sse\n\n`);
+    console.log('To use this MCP server in stdio mode, run it via `outline-mcp-server-stdio`.');
 });

package/build/outline/outlineClient.js

@@ -9,7 +9,6 @@ const API_URL = process.env.OUTLINE_API_URL || 'https://app.getoutline.com/api';
 if (!API_KEY) {
     throw new Error('OUTLINE_API_KEY environment variable is required');
 }
-console.log('Connecting to API URL:', API_URL);
 // Create axios client with authentication
 export const outlineClient = axios.create({
     baseURL: API_URL,

package/build/stdio.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env bun
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { getMcpServer } from './utils/getMcpServer.js';
+const mcpServer = await getMcpServer();
+// STDIO mode - for direct client connections
+const transport = new StdioServerTransport();
+await mcpServer.connect(transport);
+// must not write to stdout according to mcp spec
+console.error('Outline MCP Server running in STDIO mode');

package/package.json

@@ -1,14 +1,14 @@
 {
   "name": "outline-mcp-server",
-  "version": "5.0.1",
+  "version": "5.2.0",
   "description": "An MCP server for interacting with Outline's API",
   "type": "module",
   "bin": {
-    "outline-mcp-server": "./build/index.js"
+    "outline-mcp-server": "./build/index.js",
+    "outline-mcp-server-stdio": "./build/stdio.js"
   },
   "files": [
-    "build",
-    "bin"
+    "build"
   ],
   "author": {
     "name": "Matt Frey",
@@ -19,30 +19,31 @@
     "url": "https://github.com/mmmeff/outline-mcp-server"
   },
   "scripts": {
-    "build": "tsc && chmod +x build/index.js",
+    "build": "tsc && chmod +x build/index.js && chmod +x build/stdio.js",
     "prepare": "npm run build",
     "watch": "bun --watch src/index.ts",
+    "watch:stdio": "bun --watch src/stdio.ts",
     "dev": "concurrently -n 'build,inspector' -c 'blue.bold,green.bold' 'npm run watch' 'npm run inspector'",
-    "inspector": "npx @modelcontextprotocol/inspector@latest -y",
+    "inspector": "npx @modelcontextprotocol/inspector@latest",
     "start": "bun build/index.js",
     "format": "prettier --write \"src/**/*.{ts,tsx,js,jsx,json}\"",
     "semantic-release": "semantic-release"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "1.12.1",
-    "axios": "1.9.0",
-    "bun": "^1.2.15",
+    "@modelcontextprotocol/sdk": "1.13.1",
+    "axios": "1.10.0",
     "dotenv": "16.5.0",
-    "fastify": "^4.28.1",
+    "fastify": "5.4.0",
     "omit-ts": "^2.0.1",
-    "zod": "3.25.61"
+    "zod": "3.25.67"
   },
   "devDependencies": {
     "@semantic-release/changelog": "^6.0.3",
     "@semantic-release/git": "^10.0.1",
-    "@types/node": "20.x",
-    "concurrently": "^9.1.2",
-    "prettier": "^3.2.5",
+    "@types/node": "20.19.1",
+    "bun": "^1.2.17",
+    "concurrently": "^9.2.0",
+    "prettier": "3.6.0",
     "semantic-release": "^22.0.12",
     "typescript": "5.x"
   },