mcp-outline 0.1.0__tar.gz

mcp_outline-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Vortiago
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mcp_outline-0.1.0/PKG-INFO

@@ -0,0 +1,170 @@
+Metadata-Version: 2.4
+Name: mcp-outline
+Version: 0.1.0
+Summary: A Model Context Protocol (MCP) server for Outline (https://www.getoutline.com)
+Author-email: "Atle H. Havsø" <atle@havso.net>
+License: MIT License
+        
+        Copyright (c) 2025 Vortiago
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Homepage, https://github.com/Vortiago/mcp-outline
+Project-URL: Bug Tracker, https://github.com/Vortiago/mcp-outline/issues
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mcp>=0.1.0
+Requires-Dist: requests>=2.25.0
+Provides-Extra: dev
+Requires-Dist: mcp[cli]>=0.1.0; extra == "dev"
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Requires-Dist: ruff>=0.0.267; extra == "dev"
+Requires-Dist: anyio>=3.6.2; extra == "dev"
+Requires-Dist: pyright>=1.1.350; extra == "dev"
+Requires-Dist: trio>=0.22.0; extra == "dev"
+Dynamic: license-file
+
+# MCP Outline Server
+
+A Model Context Protocol (MCP) server enabling AI assistants to interact with Outline (https://www.getoutline.com)
+
+## Overview
+
+This project implements a Model Context Protocol (MCP) server that allows AI assistants (like Claude) to interact with Outline document services, providing a bridge between natural language interactions and Outline's document management capabilities.
+
+## Features
+
+Currently implemented:
+- **Document Search**: Search for documents by keywords
+- **Collection Management**: List collections and view document structure
+- **Document Reading**: Read document content, export as markdown
+- **Comment Management**: View and add comments on documents
+- **Document Creation**: Create new documents in collections
+- **Document Editing**: Update document content and move documents
+- **Backlink Management**: View documents that link to a specific document
+
+## Getting Started
+
+### Prerequisites
+
+- Python 3.10+
+- Outline account with API access
+- Outline API key (get this from your Outline account settings)
+
+### Installation
+
+```bash
+# Clone the repository
+git clone https://github.com/Vortiago/mcp-outline.git
+cd mcp-outline
+
+# Install in development mode
+uv pip install -e ".[dev]"
+```
+
+### Configuration
+
+Create a `.env` file in the project root with the following variables:
+
+```
+# Outline API Configuration
+OUTLINE_API_KEY=your_outline_api_key_here
+
+# For cloud-hosted Outline (default)
+# OUTLINE_API_URL=https://app.getoutline.com/api
+
+# For self-hosted Outline
+# OUTLINE_API_URL=https://your-outline-instance.example.com/api
+```
+
+### Running the Server
+
+```bash
+# Development mode with the MCP Inspector
+mcp dev src/mcp_outline/server.py
+
+# Or use the provided script
+./start_server.sh
+
+# Install in Claude Desktop (if available)
+mcp install src/mcp_outline/server.py --name "Document Outline Assistant"
+```
+
+## Usage Examples
+
+### Search for Documents
+
+```
+Search for documents containing "project planning"
+```
+
+### List Collections
+
+```
+Show me all available collections
+```
+
+### Read a Document
+
+```
+Get the content of document with ID "docId123"
+```
+
+### Create a New Document
+
+```
+Create a new document titled "Research Report" in collection "colId456" with content "# Introduction\n\nThis is a research report..."
+```
+
+### Add a Comment
+
+```
+Add a comment to document "docId123" saying "This looks great, but we should add more details to the methodology section."
+```
+
+### Move a Document
+
+```
+Move document "docId123" to collection "colId789"
+```
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## Development
+
+```bash
+# Run tests
+uv run pytest tests/
+
+# Format code
+uv run ruff format .
+```
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## Acknowledgments
+
+- Built with [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk)
+- Uses [Outline API](https://getoutline.com) for document management

mcp_outline-0.1.0/README.md

@@ -0,0 +1,126 @@
+# MCP Outline Server
+
+A Model Context Protocol (MCP) server enabling AI assistants to interact with Outline (https://www.getoutline.com)
+
+## Overview
+
+This project implements a Model Context Protocol (MCP) server that allows AI assistants (like Claude) to interact with Outline document services, providing a bridge between natural language interactions and Outline's document management capabilities.
+
+## Features
+
+Currently implemented:
+- **Document Search**: Search for documents by keywords
+- **Collection Management**: List collections and view document structure
+- **Document Reading**: Read document content, export as markdown
+- **Comment Management**: View and add comments on documents
+- **Document Creation**: Create new documents in collections
+- **Document Editing**: Update document content and move documents
+- **Backlink Management**: View documents that link to a specific document
+
+## Getting Started
+
+### Prerequisites
+
+- Python 3.10+
+- Outline account with API access
+- Outline API key (get this from your Outline account settings)
+
+### Installation
+
+```bash
+# Clone the repository
+git clone https://github.com/Vortiago/mcp-outline.git
+cd mcp-outline
+
+# Install in development mode
+uv pip install -e ".[dev]"
+```
+
+### Configuration
+
+Create a `.env` file in the project root with the following variables:
+
+```
+# Outline API Configuration
+OUTLINE_API_KEY=your_outline_api_key_here
+
+# For cloud-hosted Outline (default)
+# OUTLINE_API_URL=https://app.getoutline.com/api
+
+# For self-hosted Outline
+# OUTLINE_API_URL=https://your-outline-instance.example.com/api
+```
+
+### Running the Server
+
+```bash
+# Development mode with the MCP Inspector
+mcp dev src/mcp_outline/server.py
+
+# Or use the provided script
+./start_server.sh
+
+# Install in Claude Desktop (if available)
+mcp install src/mcp_outline/server.py --name "Document Outline Assistant"
+```
+
+## Usage Examples
+
+### Search for Documents
+
+```
+Search for documents containing "project planning"
+```
+
+### List Collections
+
+```
+Show me all available collections
+```
+
+### Read a Document
+
+```
+Get the content of document with ID "docId123"
+```
+
+### Create a New Document
+
+```
+Create a new document titled "Research Report" in collection "colId456" with content "# Introduction\n\nThis is a research report..."
+```
+
+### Add a Comment
+
+```
+Add a comment to document "docId123" saying "This looks great, but we should add more details to the methodology section."
+```
+
+### Move a Document
+
+```
+Move document "docId123" to collection "colId789"
+```
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## Development
+
+```bash
+# Run tests
+uv run pytest tests/
+
+# Format code
+uv run ruff format .
+```
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## Acknowledgments
+
+- Built with [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk)
+- Uses [Outline API](https://getoutline.com) for document management

mcp_outline-0.1.0/pyproject.toml

@@ -0,0 +1,58 @@
+[build-system]
+requires = ["setuptools>=42", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "mcp-outline"
+description = "A Model Context Protocol (MCP) server for Outline (https://www.getoutline.com)"
+version = "0.1.0"
+authors = [
+    {name = "Atle H. Havsø", email = "atle@havso.net"},
+]
+requires-python = ">=3.10"
+readme = "README.md"
+license = {file = "LICENSE"}
+dependencies = [
+    "mcp>=0.1.0",
+    "requests>=2.25.0",
+]
+
+[project.scripts]
+mcp-outline = "mcp_outline.server:main"
+
+[project.urls]
+"Homepage" = "https://github.com/Vortiago/mcp-outline"
+"Bug Tracker" = "https://github.com/Vortiago/mcp-outline/issues"
+
+[project.optional-dependencies]
+dev = [
+    "mcp[cli]>=0.1.0",
+    "pytest>=7.0.0",
+    "pytest-asyncio>=0.21.0",
+    "ruff>=0.0.267",
+    "anyio>=3.6.2",
+    "pyright>=1.1.350",
+    "trio>=0.22.0",
+]
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = "test_*.py"
+python_functions = "test_*"
+
+[tool.ruff]
+line-length = 79
+target-version = "py310"
+select = ["E", "F", "I"]
+extend-exclude = ["docs"]
+
+[tool.pyright]
+exclude = [
+    "**/node_modules",
+    "**/__pycache__",
+    "**/.*",
+    "docs/"
+]

mcp_outline-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

mcp_outline-0.1.0/src/mcp_outline/__init__.py

@@ -0,0 +1,4 @@
+# MCP Outline package
+"""
+MCP server for document outlines
+"""

mcp_outline-0.1.0/src/mcp_outline/__main__.py

@@ -0,0 +1,7 @@
+"""
+Main module for MCP Outline server
+"""
+from mcp_outline.server import main
+
+if __name__ == "__main__":
+    main()

mcp_outline-0.1.0/src/mcp_outline/features/__init__.py

@@ -0,0 +1,12 @@
+# Document Outline MCP features package
+from mcp_outline.features import documents
+
+
+def register_all(mcp):
+    """
+    Register all features with the MCP server.
+    
+    Args:
+        mcp: The FastMCP server instance
+    """
+    documents.register(mcp)

mcp_outline-0.1.0/src/mcp_outline/features/documents/__init__.py

@@ -0,0 +1,18 @@
+# Document management features for MCP Outline
+from typing import Optional
+from mcp_outline.features.documents import tools
+from mcp_outline.features.documents import document_reading
+from mcp_outline.features.documents import document_editing
+
+def register(mcp, api_key: Optional[str] = None, api_url: Optional[str] = None):
+    """
+    Register document management features with the MCP server.
+    
+    Args:
+        mcp: The FastMCP server instance
+        api_key: Optional API key for Outline
+        api_url: Optional API URL for Outline
+    """
+    tools.register_tools(mcp)
+    document_reading.register_tools(mcp)
+    document_editing.register_tools(mcp)

mcp_outline-0.1.0/src/mcp_outline/features/documents/common.py

@@ -0,0 +1,39 @@
+"""
+Common utilities for document outline features.
+
+This module provides shared functionality used by both tools and resources.
+"""
+import os
+from mcp_outline.utils.outline_client import OutlineClient, OutlineError
+
+class OutlineClientError(Exception):
+    """Exception raised for errors in document outline client operations."""
+    pass
+
+def get_outline_client() -> OutlineClient:
+    """
+    Get the document outline client.
+    
+    Returns:
+        OutlineClient instance
+        
+    Raises:
+        OutlineClientError: If client creation fails
+    """
+    try:
+        # Get API credentials from environment variables
+        api_key = os.getenv("OUTLINE_API_KEY")
+        api_url = os.getenv("OUTLINE_API_URL")
+        
+        # Create an instance of the outline client
+        client = OutlineClient(api_key=api_key, api_url=api_url)
+        
+        # Test the connection by attempting to get auth info
+        auth_info = client.auth_info()
+        user_name = auth_info.get('user', {}).get('name', 'Unknown')
+        
+        return client
+    except OutlineError as e:
+        raise OutlineClientError(f"Outline client error: {str(e)}")
+    except Exception as e:
+        raise OutlineClientError(f"Unexpected error: {str(e)}")

mcp_outline-0.1.0/src/mcp_outline/features/documents/document_editing.py

@@ -0,0 +1,191 @@
+"""
+Document editing tools for the MCP Outline server.
+
+This module provides MCP tools for creating and updating documents.
+"""
+from typing import Optional, Dict, Any
+
+from mcp_outline.features.documents.common import get_outline_client, OutlineClientError
+
+def register_tools(mcp) -> None:
+    """
+    Register document editing tools with the MCP server.
+    
+    Args:
+        mcp: The FastMCP server instance
+    """
+    @mcp.tool()
+    def create_document(
+        title: str,
+        collection_id: str,
+        text: str = "",
+        parent_document_id: Optional[str] = None,
+        publish: bool = True
+    ) -> str:
+        """
+        Create a new document.
+        
+        Args:
+            title: The document title
+            collection_id: The collection ID to create the document in
+            text: Optional markdown content for the document
+            parent_document_id: Optional parent document ID for nesting
+            publish: Whether to publish the document immediately
+            
+        Returns:
+            Result message with the new document ID
+        """
+        try:
+            client = get_outline_client()
+            
+            data = {
+                "title": title,
+                "text": text,
+                "collectionId": collection_id,
+                "publish": publish
+            }
+            
+            if parent_document_id:
+                data["parentDocumentId"] = parent_document_id
+                
+            response = client.post("documents.create", data)
+            document = response.get("data", {})
+            
+            if not document:
+                return "Failed to create document."
+                
+            doc_id = document.get("id", "unknown")
+            doc_title = document.get("title", "Untitled")
+            
+            return f"Document created successfully: {doc_title} (ID: {doc_id})"
+        except OutlineClientError as e:
+            return f"Error creating document: {str(e)}"
+        except Exception as e:
+            return f"Unexpected error: {str(e)}"
+    
+    @mcp.tool()
+    def update_document(
+        document_id: str,
+        title: Optional[str] = None,
+        text: Optional[str] = None,
+        append: bool = False
+    ) -> str:
+        """
+        Update an existing document.
+        
+        Args:
+            document_id: The document ID to update
+            title: New title (if None, keeps existing title)
+            text: New content (if None, keeps existing content)
+            append: If True, appends text instead of replacing
+            
+        Returns:
+            Result message
+        """
+        try:
+            client = get_outline_client()
+            
+            # Only include fields that are being updated
+            data: Dict[str, Any] = {"id": document_id}
+            
+            if title is not None:
+                data["title"] = title
+                
+            if text is not None:
+                data["text"] = text
+                data["append"] = append
+            
+            response = client.post("documents.update", data)
+            document = response.get("data", {})
+            
+            if not document:
+                return "Failed to update document."
+                
+            doc_title = document.get("title", "Untitled")
+            
+            return f"Document updated successfully: {doc_title}"
+        except OutlineClientError as e:
+            return f"Error updating document: {str(e)}"
+        except Exception as e:
+            return f"Unexpected error: {str(e)}"
+    
+    @mcp.tool()
+    def move_document(
+        document_id: str,
+        collection_id: Optional[str] = None,
+        parent_document_id: Optional[str] = None
+    ) -> str:
+        """
+        Move a document to a different collection or parent.
+        
+        Args:
+            document_id: The document ID to move
+            collection_id: Target collection ID
+            parent_document_id: Optional parent document ID
+            
+        Returns:
+            Result message
+        """
+        try:
+            client = get_outline_client()
+            
+            # Require at least one destination parameter
+            if collection_id is None and parent_document_id is None:
+                return "Error: You must specify either a collection_id or parent_document_id."
+            
+            data = {"id": document_id}
+            
+            if collection_id:
+                data["collectionId"] = collection_id
+                
+            if parent_document_id:
+                data["parentDocumentId"] = parent_document_id
+            
+            response = client.post("documents.move", data)
+            
+            # Check for successful response
+            if response.get("data"):
+                return "Document moved successfully."
+            else:
+                return "Failed to move document."
+        except OutlineClientError as e:
+            return f"Error moving document: {str(e)}"
+        except Exception as e:
+            return f"Unexpected error: {str(e)}"
+    
+    @mcp.tool()
+    def add_comment(
+        document_id: str,
+        text: str
+    ) -> str:
+        """
+        Add a comment to a document.
+        
+        Args:
+            document_id: The document to comment on
+            text: The comment text (supports markdown)
+            
+        Returns:
+            Result message with the new comment ID
+        """
+        try:
+            client = get_outline_client()
+            
+            data = {
+                "documentId": document_id,
+                "text": text
+            }
+            
+            response = client.post("comments.create", data)
+            comment = response.get("data", {})
+            
+            if not comment:
+                return "Failed to create comment."
+                
+            comment_id = comment.get("id", "unknown")
+            
+            return f"Comment added successfully (ID: {comment_id})"
+        except OutlineClientError as e:
+            return f"Error adding comment: {str(e)}"
+        except Exception as e:
+            return f"Unexpected error: {str(e)}"