omniplan-mcp 0.1.0__tar.gz

omniplan_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cygnus Yang
+
+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.

omniplan_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,279 @@
+Metadata-Version: 2.4
+Name: omniplan-mcp
+Version: 0.1.0
+Summary: MCP server for reading OmniPlan (.oplx) and Microsoft Project (.mpp) schedule files
+Author: Cygnus Yang
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/cygnusyang/omniplan-mcp
+Project-URL: Repository, https://github.com/cygnusyang/omniplan-mcp
+Project-URL: Bug Tracker, https://github.com/cygnusyang/omniplan-mcp/issues
+Keywords: mcp,omniplan,project-management,microsoft-project,schedule,claude
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business :: Scheduling
+Classifier: Topic :: Software Development :: Build Tools
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mcp>=1.0.0
+Dynamic: license-file
+
+<p align="center">
+  <img src="https://img.shields.io/badge/macOS-required-blue" alt="macOS">
+  <img src="https://img.shields.io/badge/python-≥3.10-blue" alt="Python">
+  <img src="https://img.shields.io/badge/license-MIT-green" alt="License">
+  <img src="https://img.shields.io/github/v/release/cygnusyang/omniplan-mcp" alt="Release">
+</p>
+
+# OmniPlan MCP Server
+
+A [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server that lets Claude read and analyze project schedule files — **OmniPlan (.oplx)** and **Microsoft Project (.mpp)** formats.
+
+Ask Claude questions like:
+- *"What's the current project schedule?"*
+- *"List all milestones and their dates"*
+- *"Show me tasks related to the robotic arm"*
+- *"What's the overall progress percentage?"*
+
+## Features
+
+| Feature | Description |
+|---------|-------------|
+| 📂 **Read .mpp** | Parse Microsoft Project files via OmniPlan bridge |
+| 📂 **Read .oplx** | Direct XML parsing (no OmniPlan needed) |
+| 🏛️ **Full hierarchy** | Groups, tasks, milestones with dates and progress |
+| 🔍 **Search** | Find tasks by keyword across the entire schedule |
+| 👤 **Resources** | List all human resources and assignments |
+| 📊 **Summary** | Phase overview, progress statistics, timeline |
+| 🔒 **Safe concurrency** | Cross-process lock prevents conflicts when multiple Claude sessions run |
+
+## Prerequisites
+
+| Requirement | Notes |
+|-------------|-------|
+| **macOS** | Required (for AppleScript/OmniPlan bridge) |
+| **Python 3.10+** | For running the MCP server |
+| **OmniPlan** | Only needed for `.mpp` files; `.oplx` works without it |
+
+### Install OmniPlan (optional — only for .mpp files)
+
+```bash
+brew install --cask omniplan
+```
+
+> **First run**: macOS may prompt for Accessibility/Automation permissions when OmniPlan is called via AppleScript. Grant them in **System Settings → Privacy & Security → Automation**.
+
+## Quick Start
+
+### 1. Install
+
+```bash
+# Option A: One-line installer (recommended)
+curl -fsSL https://raw.githubusercontent.com/cygnusyang/omniplan-mcp/main/install.sh | bash
+
+# Option B: Manual clone
+git clone https://github.com/cygnusyang/omniplan-mcp.git
+cd omniplan-mcp
+pip install -e .
+```
+
+### 2. Configure Claude Code
+
+Add to your `~/.claude/settings.json`:
+
+<details>
+<summary><b>uv run (recommended)</b></summary>
+
+```json
+{
+  "mcpServers": {
+    "omniplan": {
+      "command": "uv",
+      "args": [
+        "run",
+        "--directory", "/Users/yourusername/.local/share/omniplan-mcp",
+        "omniplan-mcp"
+      ],
+      "env": {}
+    }
+  }
+}
+```
+</details>
+
+<details>
+<summary><b>pip install (after PyPI publish)</b></summary>
+
+```json
+{
+  "mcpServers": {
+    "omniplan": {
+      "command": "uvx",
+      "args": ["omniplan-mcp"],
+      "env": {}
+    }
+  }
+}
+```
+</details>
+
+<details>
+<summary><b>Direct Python</b></summary>
+
+```json
+{
+  "mcpServers": {
+    "omniplan": {
+      "command": "/path/to/python3",
+      "args": ["-m", "omniplan_mcp"],
+      "env": {
+        "PYTHONPATH": "/path/to/omniplan-mcp/src"
+      }
+    }
+  }
+}
+```
+</details>
+
+### 3. Restart Claude Code
+
+The MCP server will start automatically. You can now ask Claude about your project files!
+
+## Usage Examples
+
+### Read a project schedule
+
+```
+你：帮我读取 PLB1011 项目计划，看看有哪些阶段
+Claude：调用 read_schedule → 显示完整任务树
+```
+
+### List milestones
+
+```
+你：列出所有里程碑节点
+Claude：调用 list_milestones → 显示所有 ◇ 里程碑
+```
+
+### Search for tasks
+
+```
+你：搜索所有关于"机械臂"的任务
+Claude：调用 search_tasks → 显示匹配的任务列表
+```
+
+### Project summary
+
+```
+你：这个项目的整体进度怎么样？
+Claude：调用 schedule_summary → 显示阶段概览和进度统计
+```
+
+## Tools Reference
+
+| Tool | Description | Parameters |
+|------|-------------|------------|
+| `read_schedule` | Full task hierarchy with dates and progress | `filepath` (required), `format`: tree/flat/json |
+| `list_milestones` | All milestone tasks | `filepath` |
+| `list_resources` | All human resources | `filepath` |
+| `search_tasks` | Search tasks by keyword | `filepath`, `keyword` |
+| `schedule_summary` | Phase overview and progress stats | `filepath` |
+
+## How It Works
+
+```
+.mpp file ──→ OmniPlan (AppleScript) ──→ .oplx (XML) ──→ MCP Server ──→ Claude
+                          ↑
+.oplx file ───────────────┴─── direct XML parsing ──────┘
+```
+
+### For .oplx files
+Direct XML parsing — fast, no external dependencies.
+
+### For .mpp files
+1. MCP server opens the `.mpp` file in OmniPlan via AppleScript
+2. Exports to `.oplx` format
+3. Parses the exported XML
+4. Cleans up temporary files
+
+> A **cross-process file lock** prevents AppleScript conflicts when multiple Claude Code sessions run simultaneously.
+
+## Project Structure
+
+```
+omniplan-mcp/
+├── install.sh                  # One-click installer
+├── pyproject.toml              # Package metadata (PyPI-ready)
+├── README.md                   # This file
+├── LICENSE                     # MIT license
+├── .gitignore
+├── src/
+│   └── omniplan_mcp/
+│       ├── __init__.py         # Package version
+│       ├── __main__.py         # CLI entry point
+│       ├── server.py           # MCP server (tools & handlers)
+│       ├── parser.py           # .mpp / .oplx file parsing
+│       └── lock.py             # Cross-process file lock
+└── tests/
+    └── test_parser.py          # Unit tests
+```
+
+## Development
+
+```bash
+# Clone
+git clone https://github.com/cygnusyang/omniplan-mcp.git
+cd omniplan-mcp
+
+# Install in editable mode
+pip install -e .
+
+# Run tests
+python -m pytest tests/
+
+# Run the server directly (stdio)
+python -m omniplan_mcp
+```
+
+### Publishing to PyPI
+
+```bash
+# Install build tools
+pip install build twine
+
+# Build
+python -m build
+
+# Upload to TestPyPI first
+twine upload --repository testpypi dist/*
+
+# Upload to PyPI
+twine upload dist/*
+```
+
+## Requirements
+
+- **Python 3.10+**
+- **macOS** (for OmniPlan AppleScript bridge)
+- **OmniPlan** (only for `.mpp` files; optional for `.oplx`)
+
+## Limitations
+
+- `.mpp` parsing requires OmniPlan to be installed
+- Only supports macOS (AppleScript dependency)
+- Does not modify `.mpp` files — read-only
+
+## License
+
+MIT License — see [LICENSE](LICENSE) for details.
+
+## Related
+
+- [Model Context Protocol](https://modelcontextprotocol.io)
+- [OmniPlan](https://www.omnigroup.com/omniplan/)
+- [Claude Code MCP Servers](https://docs.anthropic.com/en/docs/claude-code/mcp-servers)

omniplan_mcp-0.1.0/README.md

@@ -0,0 +1,254 @@
+<p align="center">
+  <img src="https://img.shields.io/badge/macOS-required-blue" alt="macOS">
+  <img src="https://img.shields.io/badge/python-≥3.10-blue" alt="Python">
+  <img src="https://img.shields.io/badge/license-MIT-green" alt="License">
+  <img src="https://img.shields.io/github/v/release/cygnusyang/omniplan-mcp" alt="Release">
+</p>
+
+# OmniPlan MCP Server
+
+A [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server that lets Claude read and analyze project schedule files — **OmniPlan (.oplx)** and **Microsoft Project (.mpp)** formats.
+
+Ask Claude questions like:
+- *"What's the current project schedule?"*
+- *"List all milestones and their dates"*
+- *"Show me tasks related to the robotic arm"*
+- *"What's the overall progress percentage?"*
+
+## Features
+
+| Feature | Description |
+|---------|-------------|
+| 📂 **Read .mpp** | Parse Microsoft Project files via OmniPlan bridge |
+| 📂 **Read .oplx** | Direct XML parsing (no OmniPlan needed) |
+| 🏛️ **Full hierarchy** | Groups, tasks, milestones with dates and progress |
+| 🔍 **Search** | Find tasks by keyword across the entire schedule |
+| 👤 **Resources** | List all human resources and assignments |
+| 📊 **Summary** | Phase overview, progress statistics, timeline |
+| 🔒 **Safe concurrency** | Cross-process lock prevents conflicts when multiple Claude sessions run |
+
+## Prerequisites
+
+| Requirement | Notes |
+|-------------|-------|
+| **macOS** | Required (for AppleScript/OmniPlan bridge) |
+| **Python 3.10+** | For running the MCP server |
+| **OmniPlan** | Only needed for `.mpp` files; `.oplx` works without it |
+
+### Install OmniPlan (optional — only for .mpp files)
+
+```bash
+brew install --cask omniplan
+```
+
+> **First run**: macOS may prompt for Accessibility/Automation permissions when OmniPlan is called via AppleScript. Grant them in **System Settings → Privacy & Security → Automation**.
+
+## Quick Start
+
+### 1. Install
+
+```bash
+# Option A: One-line installer (recommended)
+curl -fsSL https://raw.githubusercontent.com/cygnusyang/omniplan-mcp/main/install.sh | bash
+
+# Option B: Manual clone
+git clone https://github.com/cygnusyang/omniplan-mcp.git
+cd omniplan-mcp
+pip install -e .
+```
+
+### 2. Configure Claude Code
+
+Add to your `~/.claude/settings.json`:
+
+<details>
+<summary><b>uv run (recommended)</b></summary>
+
+```json
+{
+  "mcpServers": {
+    "omniplan": {
+      "command": "uv",
+      "args": [
+        "run",
+        "--directory", "/Users/yourusername/.local/share/omniplan-mcp",
+        "omniplan-mcp"
+      ],
+      "env": {}
+    }
+  }
+}
+```
+</details>
+
+<details>
+<summary><b>pip install (after PyPI publish)</b></summary>
+
+```json
+{
+  "mcpServers": {
+    "omniplan": {
+      "command": "uvx",
+      "args": ["omniplan-mcp"],
+      "env": {}
+    }
+  }
+}
+```
+</details>
+
+<details>
+<summary><b>Direct Python</b></summary>
+
+```json
+{
+  "mcpServers": {
+    "omniplan": {
+      "command": "/path/to/python3",
+      "args": ["-m", "omniplan_mcp"],
+      "env": {
+        "PYTHONPATH": "/path/to/omniplan-mcp/src"
+      }
+    }
+  }
+}
+```
+</details>
+
+### 3. Restart Claude Code
+
+The MCP server will start automatically. You can now ask Claude about your project files!
+
+## Usage Examples
+
+### Read a project schedule
+
+```
+你：帮我读取 PLB1011 项目计划，看看有哪些阶段
+Claude：调用 read_schedule → 显示完整任务树
+```
+
+### List milestones
+
+```
+你：列出所有里程碑节点
+Claude：调用 list_milestones → 显示所有 ◇ 里程碑
+```
+
+### Search for tasks
+
+```
+你：搜索所有关于"机械臂"的任务
+Claude：调用 search_tasks → 显示匹配的任务列表
+```
+
+### Project summary
+
+```
+你：这个项目的整体进度怎么样？
+Claude：调用 schedule_summary → 显示阶段概览和进度统计
+```
+
+## Tools Reference
+
+| Tool | Description | Parameters |
+|------|-------------|------------|
+| `read_schedule` | Full task hierarchy with dates and progress | `filepath` (required), `format`: tree/flat/json |
+| `list_milestones` | All milestone tasks | `filepath` |
+| `list_resources` | All human resources | `filepath` |
+| `search_tasks` | Search tasks by keyword | `filepath`, `keyword` |
+| `schedule_summary` | Phase overview and progress stats | `filepath` |
+
+## How It Works
+
+```
+.mpp file ──→ OmniPlan (AppleScript) ──→ .oplx (XML) ──→ MCP Server ──→ Claude
+                          ↑
+.oplx file ───────────────┴─── direct XML parsing ──────┘
+```
+
+### For .oplx files
+Direct XML parsing — fast, no external dependencies.
+
+### For .mpp files
+1. MCP server opens the `.mpp` file in OmniPlan via AppleScript
+2. Exports to `.oplx` format
+3. Parses the exported XML
+4. Cleans up temporary files
+
+> A **cross-process file lock** prevents AppleScript conflicts when multiple Claude Code sessions run simultaneously.
+
+## Project Structure
+
+```
+omniplan-mcp/
+├── install.sh                  # One-click installer
+├── pyproject.toml              # Package metadata (PyPI-ready)
+├── README.md                   # This file
+├── LICENSE                     # MIT license
+├── .gitignore
+├── src/
+│   └── omniplan_mcp/
+│       ├── __init__.py         # Package version
+│       ├── __main__.py         # CLI entry point
+│       ├── server.py           # MCP server (tools & handlers)
+│       ├── parser.py           # .mpp / .oplx file parsing
+│       └── lock.py             # Cross-process file lock
+└── tests/
+    └── test_parser.py          # Unit tests
+```
+
+## Development
+
+```bash
+# Clone
+git clone https://github.com/cygnusyang/omniplan-mcp.git
+cd omniplan-mcp
+
+# Install in editable mode
+pip install -e .
+
+# Run tests
+python -m pytest tests/
+
+# Run the server directly (stdio)
+python -m omniplan_mcp
+```
+
+### Publishing to PyPI
+
+```bash
+# Install build tools
+pip install build twine
+
+# Build
+python -m build
+
+# Upload to TestPyPI first
+twine upload --repository testpypi dist/*
+
+# Upload to PyPI
+twine upload dist/*
+```
+
+## Requirements
+
+- **Python 3.10+**
+- **macOS** (for OmniPlan AppleScript bridge)
+- **OmniPlan** (only for `.mpp` files; optional for `.oplx`)
+
+## Limitations
+
+- `.mpp` parsing requires OmniPlan to be installed
+- Only supports macOS (AppleScript dependency)
+- Does not modify `.mpp` files — read-only
+
+## License
+
+MIT License — see [LICENSE](LICENSE) for details.
+
+## Related
+
+- [Model Context Protocol](https://modelcontextprotocol.io)
+- [OmniPlan](https://www.omnigroup.com/omniplan/)
+- [Claude Code MCP Servers](https://docs.anthropic.com/en/docs/claude-code/mcp-servers)

omniplan_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["setuptools>=68.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "omniplan-mcp"
+version = "0.1.0"
+description = "MCP server for reading OmniPlan (.oplx) and Microsoft Project (.mpp) schedule files"
+readme = "README.md"
+license = "MIT"
+authors = [
+    { name = "Cygnus Yang" }
+]
+keywords = ["mcp", "omniplan", "project-management", "microsoft-project", "schedule", "claude"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Office/Business :: Scheduling",
+    "Topic :: Software Development :: Build Tools",
+]
+requires-python = ">=3.10"
+dependencies = [
+    "mcp>=1.0.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/cygnusyang/omniplan-mcp"
+Repository = "https://github.com/cygnusyang/omniplan-mcp"
+"Bug Tracker" = "https://github.com/cygnusyang/omniplan-mcp/issues"
+
+[project.scripts]
+omniplan-mcp = "omniplan_mcp.__main__:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]

omniplan_mcp-0.1.0/setup.cfg

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

omniplan_mcp-0.1.0/src/omniplan_mcp/__init__.py

@@ -0,0 +1,34 @@
+#!/usr/bin/env python3
+"""
+OmniPlan MCP Server
+
+A Model Context Protocol (MCP) server that reads and analyzes project schedule files
+in OmniPlan (.oplx) and Microsoft Project (.mpp) formats.
+
+## Features
+
+- Read .mpp files via OmniPlan AppleScript bridge
+- Read .oplx files via direct XML parsing
+- List milestones, resources, tasks
+- Search tasks by keyword
+- Project schedule summary with progress stats
+
+## Usage (as CLI)
+
+    pip install -e .
+    omniplan-mcp
+
+## Usage (as MCP server)
+
+Add to Claude Code settings.json:
+
+    "mcpServers": {
+        "omniplan": {
+            "command": "uv",
+            "args": ["run", "--directory", "/path/to/omniplan-mcp", "omniplan-mcp"],
+            "env": {}
+        }
+    }
+"""
+
+__version__ = "0.1.0"

omniplan_mcp-0.1.0/src/omniplan_mcp/__main__.py

@@ -0,0 +1,39 @@
+"""
+Entry point for the omniplan-mcp server.
+
+Run directly:
+    python -m omniplan_mcp
+"""
+
+import asyncio
+
+import mcp.server.stdio
+from mcp.server import NotificationOptions
+
+from . import __version__
+from .server import server
+
+
+def main():
+    """Run the MCP server over stdio transport."""
+    asyncio.run(_run())
+
+
+async def _run():
+    async with mcp.server.stdio.stdio_server() as (read_stream, write_stream):
+        await server.run(
+            read_stream,
+            write_stream,
+            InitializationOptions(
+                server_name="omniplan-mcp",
+                server_version=__version__,
+                capabilities=server.get_capabilities(
+                    notification_options=NotificationOptions(),
+                    experimental_capabilities={},
+                ),
+            ),
+        )
+
+
+if __name__ == "__main__":
+    main()