obsidian-accomplishments-mcp 0.1.10 → 0.1.12

package/README.md

@@ -1,29 +1,25 @@
-# Obsidian MCP Server
+# Obsidian Project Management MCP Server
 
-An MCP (Model Context Protocol) server that enables AI assistants to manage structured project accomplishments in Obsidian. Works alongside the [Canvas Structured Items Plugin](https://bitbucket.org/ostanmarc/obsidian-canvas-structured-items/src/master/) for visual project management.
+An MCP (Model Context Protocol) server for AI-native project management in Obsidian. Enables AI assistants to create, update, search, and manage project entities stored as markdown files with automatic relationship tracking.
 
 ## What This Does
 
 This MCP server lets AI assistants:
-- **Manage accomplishments** — create, update, and track work items with outcomes, acceptance criteria, and tasks
-- **Handle dependencies** — define what blocks what, find blocked items, and identify what's ready to start
-- **Track progress** — see project status, current work, and completion statistics
-- **Read and write documents** — access reference materials organized in workspaces
+- **Manage project entities** — create, update, and track milestones, stories, tasks, decisions, documents, and features
+- **Handle dependencies** — define relationships between entities with automatic bidirectional sync
+- **Track progress** — see project status, workstream health, and feature coverage
+- **Navigate hierarchies** — traverse parent-child relationships and dependency graphs
+- **Batch operations** — efficient bulk create/update/archive with dry-run preview
 
 ```
 ┌─────────────────────────────────────────────────────────────────────┐
 │                        Your Workflow                                │
 ├─────────────────────────────────────────────────────────────────────┤
 │                                                                     │
-│   ┌──────────┐      ┌──────────────┐      ┌──────────┐            │
-│   │ Obsidian │◄────►│  MCP Server  │◄────►│    AI    │            │
-│   │  Canvas  │      │  (this repo) │      │ Assistant│            │
-│   └────┬─────┘      └──────────────┘      └──────────┘            │
-│        │                                                           │
-│        ▼                                                           │
-│   ┌──────────┐      ┌──────────────┐                              │
-│   │  Plugin  │─────►│    Notion    │  (optional sync)             │
-│   └──────────┘      └──────────────┘                              │
+│   ┌──────────┐      ┌──────────────┐      ┌──────────┐              │
+│   │ Obsidian │◄────►│  MCP Server  │◄────►│    AI    │              │
+│   │  Vault   │      │  (this repo) │      │ Assistant│              │
+│   └──────────┘      └──────────────┘      └──────────┘              │
 │                                                                     │
 └─────────────────────────────────────────────────────────────────────┘
 ```
@@ -36,24 +32,11 @@ This MCP server lets AI assistants:
 
 - Node.js 18 or later
 - An Obsidian vault
-- The [Canvas Structured Items Plugin](https://bitbucket.org/ostanmarc/obsidian-canvas-structured-items/src/master/) installed in your vault
 
-### Option 1: Install from npm (Recommended)
+### Install from Source
 
 ```bash
-npm install -g obsidian-accomplishments-mcp
-```
-
-Or run directly with npx:
-
-```bash
-npx obsidian-accomplishments-mcp
-```
-
-### Option 2: Install from Source
-
-```bash
-git clone https://github.com/ostanlabs/obsidian_mcp.git
+git clone <repository-url>
 cd obsidian_mcp
 npm install
 npm run build
@@ -65,7 +48,17 @@ Create the required folder structure in your Obsidian vault:
 
 ```
 your-vault/
-├── accomplishments/          # Accomplishment markdown files
+├── milestones/               # Milestone files (M-xxx.md)
+├── stories/                  # Story files (S-xxx.md)
+├── tasks/                    # Task files (T-xxx.md)
+├── decisions/                # Decision files (DEC-xxx.md)
+├── documents/                # Document files (DOC-xxx.md)
+├── features/                 # Feature files (F-xxx.md)
+├── archive/                  # Archived entities (by type)
+│   ├── milestone/
+│   ├── story/
+│   ├── task/
+│   └── ...
 ├── projects/
 │   └── main.canvas           # Your project canvas
 └── workspaces.json           # Workspace configuration (auto-created on first run)
@@ -77,40 +70,6 @@ Add the MCP server to your AI client's configuration.
 
 **For Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
 
-Using npx (recommended):
-```json
-{
-  "mcpServers": {
-    "obsidian": {
-      "command": "npx",
-      "args": ["-y", "obsidian-accomplishments-mcp@latest"],
-      "env": {
-        "VAULT_PATH": "/absolute/path/to/your/obsidian/vault",
-        "ACCOMPLISHMENTS_FOLDER": "accomplishments",
-        "DEFAULT_CANVAS": "projects/main.canvas"
-      }
-    }
-  }
-}
-```
-
-Using global install:
-```json
-{
-  "mcpServers": {
-    "obsidian": {
-      "command": "obsidian-accomplishments-mcp",
-      "env": {
-        "VAULT_PATH": "/absolute/path/to/your/obsidian/vault",
-        "ACCOMPLISHMENTS_FOLDER": "accomplishments",
-        "DEFAULT_CANVAS": "projects/main.canvas"
-      }
-    }
-  }
-}
-```
-
-Using local install:
 ```json
 {
   "mcpServers": {
@@ -119,7 +78,6 @@ Using local install:
       "args": ["/path/to/obsidian_mcp/dist/index.js"],
       "env": {
         "VAULT_PATH": "/absolute/path/to/your/obsidian/vault",
-        "ACCOMPLISHMENTS_FOLDER": "accomplishments",
         "DEFAULT_CANVAS": "projects/main.canvas"
       }
     }
@@ -132,8 +90,7 @@ Using local install:
 | Variable | Required | Description |
 |----------|----------|-------------|
 | `VAULT_PATH` | Yes | Absolute path to your Obsidian vault |
-| `ACCOMPLISHMENTS_FOLDER` | Yes | Folder for accomplishment files (relative to vault) |
-| `DEFAULT_CANVAS` | Yes | Path to your main project canvas file (relative to vault) |
+| `DEFAULT_CANVAS` | No | Path to your main project canvas file (relative to vault) |
 
 ### Configure Workspaces
 
@@ -152,116 +109,117 @@ On first run, the server creates a `workspaces.json` file in your vault. Edit th
 }
 ```
 
-Each workspace is a named folder containing markdown files that the AI can read and write.
-
 ---
 
 ## Core Concepts
 
-### Accomplishments
-
-An **accomplishment** is the atomic unit of work. Each accomplishment has:
-
-- **Title** — A clear name for the work item
-- **Outcome** — What will be true when this is done
-- **Acceptance Criteria** — Checkboxes defining completion
-- **Tasks** — Specific steps to achieve the outcome
-- **Dependencies** — Other accomplishments that must finish first
-- **Status** — Not Started, In Progress, Completed, or Blocked
-- **Effort Type** — Business, Engineering, Infra, or Research
-- **Priority** — Low, Medium, High, or Critical
+### Entity Hierarchy
 
-Example accomplishment file:
+The system uses a hierarchical entity model:
 
-```markdown
----
-type: accomplishment
-title: User Authentication
-id: ACC-001
-effort: Engineering
-status: In Progress
-priority: High
-inProgress: true
-depends_on: ["ACC-000"]
----
-
-# User Authentication (Accomplishment)
-
-## Outcome
-Users can securely log in and maintain sessions.
-
-## Acceptance Criteria
-- [ ] Login form validates credentials
-- [ ] Sessions persist across browser refreshes
-- [ ] Logout clears session completely
-
-## Tasks
-
-### Task 1: Design Auth Flow
-- **Goal:** Document the authentication sequence
-- **Estimate:** 2h
-- **Status:** Complete
+```
+Milestone (M-xxx)
+└── Story (S-xxx)
+    └── Task (T-xxx)
 
-### Task 2: Implement Login API
-- **Goal:** Create backend authentication endpoint
-- **Estimate:** 4h
-- **Status:** InProgress
+Feature (F-xxx)     ─── product features with coverage tracking
+Decision (DEC-xxx)  ─── captured choices, can affect other entities
+Document (DOC-xxx)  ─── specs/ADRs, can be implemented by stories
 ```
 
-### Canvas as Project Board
+### Entity Types
+
+| Type | ID Format | Key Fields |
+|------|-----------|------------|
+| **Milestone** | `M-001` | `target_date`, `owner`, `priority` |
+| **Story** | `S-001` | `parent` (milestone), `priority`, `acceptance_criteria` |
+| **Task** | `T-001` | `parent` (story), `estimate_hrs`, `assignee` |
+| **Decision** | `DEC-001` | `decided_by`, `decided_on`, `affects`, `supersedes` |
+| **Document** | `DOC-001` | `doc_type`, `version`, `implemented_by` |
+| **Feature** | `F-001` | `tier`, `phase`, `documented_by`, `implemented_by` |
+
+### Entity Status
+
+| Entity | Statuses |
+|--------|----------|
+| Milestone, Story | `Not Started`, `In Progress`, `Completed`, `Blocked` |
+| Task | `Open`, `InProgress`, `Complete`, `OnHold` |
+| Decision | `Pending`, `Decided`, `Superseded` |
+| Document | `Draft`, `Review`, `Approved`, `Superseded` |
+| Feature | `Planned`, `In Progress`, `Complete`, `Deferred` |
+
+### Relationships (Auto-Synced)
+
+All relationships are bidirectional and automatically synchronized:
+
+| Relationship | Forward Field | Reverse Field |
+|--------------|---------------|---------------|
+| Hierarchy | `parent` | `children` |
+| Dependency | `depends_on` | `blocks` |
+| Implementation | `implements` | `implemented_by` |
+| Supersession | `supersedes` | `superseded_by` |
+| Documentation | `documents` | `documented_by` |
+
+### Workstreams
+
+Entities are organized by workstream. Values are automatically normalized:
+- `infrastructure`, `infra` → `infra`
+- `eng`, `engineering` → `engineering`
+- `biz`, `business` → `business`
+- `ops`, `operations` → `operations`
+- `r&d`, `rnd`, `research` → `research`
+- `ux`, `ui`, `design` → `design`
+- `mktg`, `marketing` → `marketing`
 
-The `.canvas` file provides a visual project view:
+---
 
-- **Nodes** = Accomplishments (colored by effort type)
-- **Arrows** = Dependencies (A → B means "B depends on A")
-- **Position** = Workflow stage (left-to-right progression)
-- **Red border** = Currently being worked on (`inProgress: true`)
+## Available Tools
 
-### Workspaces
+The MCP server provides 15 tools organized by function:
 
-Workspaces are named document collections that the AI can access. Configure them in `workspaces.json` to give the AI access to:
-- Project documentation
-- Meeting notes
-- Reference materials
-- Any other markdown files
+### Entity Management
 
----
+| Tool | Description |
+|------|-------------|
+| `create_entity` | Create a new entity (milestone, story, task, decision, document, or feature) |
+| `update_entity` | Update fields, status, relationships, or archive/restore. Returns before/after diff. |
 
-## Available Tools
+### Batch Operations
 
-The MCP server provides 14 tools organized by function:
+| Tool | Description |
+|------|-------------|
+| `batch_update` | Bulk create/update/archive with `dry_run` preview and `include_entities` option |
 
-### Accomplishment Management
+### Project Understanding
 
 | Tool | Description |
 |------|-------------|
-| `manage_accomplishment` | Create, update, or delete accomplishments |
-| `get_accomplishment` | Get full details of a specific accomplishment |
-| `list_accomplishments` | List all accomplishments with optional status filter |
+| `get_project_overview` | High-level project status with workstream filtering |
+| `analyze_project_state` | Deep analysis with blockers and recommendations |
+| `get_feature_coverage` | Feature implementation/documentation coverage with `summary_only` option |
 
-### Task Management
+### Search & Navigation
 
 | Tool | Description |
 |------|-------------|
-| `manage_task` | Add, update, or remove tasks within an accomplishment |
-| `set_work_focus` | Set which accomplishment/task is currently being worked on |
+| `search_entities` | Full-text search, list with filters, or navigate hierarchy |
+| `get_entity` | Get single entity with selective field retrieval |
+| `get_entities` | Bulk fetch multiple entities (~75% token savings) |
 
-### Dependency Management
+### Document Management
 
 | Tool | Description |
 |------|-------------|
-| `manage_dependency` | Add or remove dependencies between accomplishments |
+| `manage_documents` | Decision history, versioning, freshness checks |
 
-### Project Status
+### Maintenance
 
 | Tool | Description |
 |------|-------------|
-| `get_project_status` | Get project statistics and overview |
-| `get_current_work` | Get items marked as in-progress |
-| `get_blocked_items` | Get items waiting on incomplete dependencies |
-| `get_ready_to_start` | Get items with all dependencies complete |
+| `reconcile_relationships` | Fix inconsistent bidirectional relationships |
+| `get_schema` | Get entity schema information |
 
-### Document Management
+### Utility Tools
 
 | Tool | Description |
 |------|-------------|
@@ -278,72 +236,86 @@ Once configured, ask your AI assistant things like:
 
 ### Project Overview
 > "What's the status of my project?"
-> "Show me what's currently in progress"
+> "Show me the engineering workstream status"
 > "What items are blocked?"
-> "What can I start working on?"
+> "Analyze the project and identify risks"
 
-### Managing Accomplishments
-> "Create an accomplishment for building the payment system"
-> "Mark ACC-001 as complete"
-> "Set ACC-005 as my current focus"
-> "What are the details of ACC-003?"
-
-### Managing Tasks
-> "Add a task to ACC-003 for writing unit tests"
-> "Mark task 2 of ACC-001 as complete"
-> "What tasks are left on ACC-002?"
+### Managing Entities
+> "Create a milestone for Q1 launch with target date March 31"
+> "Create a story under M-001 for user authentication"
+> "Add a task to S-003 for writing unit tests"
+> "Mark T-005 as completed"
 
 ### Dependencies
-> "ACC-004 depends on ACC-002 and ACC-003"
-> "Remove the dependency from ACC-005 to ACC-001"
-> "What's blocking ACC-006?"
+> "S-004 depends on S-002 and S-003"
+> "What's blocking S-006?"
+> "Show me the dependency graph for M-001"
+
+### Decisions & Documents
+> "Create a decision about using PostgreSQL vs MongoDB"
+> "What decisions have been made about authentication?"
+> "Create a spec document for the API design"
+> "Is DOC-003 up to date with recent decisions?"
+
+### Features
+> "What's the feature coverage for Phase 2?"
+> "Which features are missing documentation?"
+> "Show me F-001's implementation status"
 
 ### Documents
 > "What workspaces are available?"
 > "List files in the docs workspace"
 > "Read the architecture document"
-> "Add a section about API design to the architecture doc"
-> "Create a new meeting notes document"
-
----
-
-## Notion Sync (Optional)
-
-The [Canvas Structured Items Plugin](https://bitbucket.org/ostanmarc/obsidian-canvas-structured-items/src/master/) can sync accomplishments to Notion:
-
-1. Configure Notion API key and database ID in the plugin settings
-2. Accomplishments sync automatically when saved
-3. Dependencies become Notion relations
-4. Two-way sync keeps both systems updated
-
-This lets your team see project status in Notion while you manage everything from Obsidian.
 
 ---
 
 ## Development
 
 ```bash
+# Install dependencies
+npm install
+
 # Build the project
 npm run build
 
-# Watch mode for development
-npm run dev
-
 # Run tests
 npm test
-```
 
-The server communicates via MCP protocol over stdio. Test by configuring it in an MCP-compatible client.
+# Run tests in watch mode
+npm run test:watch
 
----
+# Type check
+npm run typecheck
+```
 
-## Technical Reference
+### Project Structure
 
-For detailed API specifications, data models, and implementation details, see [Technical Specification](docs/MCP_TECHNICAL_SPEC.md).
+```
+src/
+├── index.ts              # MCP server entry point
+├── models/
+│   └── v2-types.ts       # Entity type definitions
+├── services/v2/
+│   ├── entity-parser.ts      # Parse markdown to entities
+│   ├── entity-serializer.ts  # Serialize entities to markdown
+│   ├── entity-validator.ts   # Validate entity data
+│   ├── index-manager.ts      # Entity indexing
+│   ├── lifecycle-manager.ts  # Status transitions
+│   ├── archive-manager.ts    # Archive/restore
+│   ├── workstream-normalizer.ts  # Workstream normalization
+│   ├── cycle-detector.ts     # Dependency cycle detection
+│   └── v2-runtime.ts         # Main runtime
+└── tools/
+    ├── index.ts              # Tool definitions
+    ├── entity-management-tools.ts
+    ├── batch-operations-tools.ts
+    ├── project-understanding-tools.ts
+    ├── search-navigation-tools.ts
+    └── decision-document-tools.ts
+```
 
 ---
 
 ## License
 
 MIT
-