# docx-mcp-server

**Your Word docs, but you talk to them instead of opening them.**

Clone this repo, configure it in 60 seconds, then say *"summarize the cloud architecture doc on my desktop"* and get back a full topology analysis with a Mermaid diagram. No file paths. No clicking around. Just ask.

## Quick Start

```bash
git clone https://github.com/bradygaster/docx-mcp-server.git
cd docx-mcp-server
npm install && npm run build
```

Configure it in [Copilot CLI](#configure-in-copilot-cli) or [VS Code](#configure-in-vs-code), then start talking to your docs.

## Just Talk to It

**The old way:**  
Copy the file path → paste it into a prompt → hope you got the slashes right.

**The new way:**  
*"Summarize the cloud architecture doc on my desktop"*

And you get this back:

```
The document describes a three-tier Azure architecture:
- Front-end: Static web apps on Azure CDN
- API layer: Azure Functions with Event Grid for async workflows
- Data tier: Cosmos DB with Redis cache

Key decision: Event-driven architecture for scalability...
```

Plus a generated Mermaid diagram of the whole topology.

### What you can ask

- *"Summarize the demo script I downloaded"* → Section-by-section breakdown with key talking points
- *"Search for 'authentication' in the API proposal on my desktop"* → Exact matches with surrounding context
- *"What Word docs do I have in Downloads?"* → Full list with file sizes and dates
- *"Open the RFP and tell me the deadline"* → Reads the doc, finds the date, tells you

### What's happening under the hood

You say **"cloud architecture doc on my desktop"** and the server:
1. Searches Desktop (including OneDrive-synced folders)
2. Finds files matching "cloud architecture" (fuzzy, case-insensitive)
3. Resolves the path and reads the document
4. Returns the full text to your AI

No file picker. No path copy-paste. Just natural language.

## Squad Integration

This repo ships with a pre-configured AI team in the `.squad/` directory. If you have `@bradygaster/squad` installed, you can say:

**"Squad, summarize the RFP on my desktop"**

And the team reads and analyzes it for you:

- **Keaton (Squad Lead)** — Coordinates the team, analyzes document structure and architecture
- **Fenster (Backend Dev)** — Handles the document parsing and data extraction
- **Hockney (QA Analyst)** — Validates the findings and cross-checks facts

The team collaborates using the same MCP tools — `resolve_document`, `read_document`, `search_document` — but coordinates the work. It's like having three analysts who can read any Word doc you throw at them.

**Without Squad:** You talk directly to Copilot with docx-mcp-server's tools available.  
**With Squad:** You talk to a team that uses those tools collaboratively to analyze complex documents.

[Learn more about Squad →](https://github.com/bradygaster/squad)

## How It Works

The `resolve_document` tool is the magic. When you say "cloud architecture doc on my desktop":

1. **Searches the right places** — Desktop, Downloads, Documents, current directory, *plus* OneDrive-synced versions of those folders
2. **Matches flexibly** — exact name, prefix match, or substring match (all case-insensitive). Say "quarterly" and it finds `Quarterly-Report-Q4.docx`
3. **Understands location hints** — "on my desktop" or "in downloads" narrows the search
4. **Handles ambiguity** — multiple matches? You get a list to pick from

The AI chains tools automatically: resolve the friendly name → read the document → summarize/search/analyze. All from one sentence.

## Configure in Copilot CLI

Add to your `~/.copilot/mcp-config.json`:

**Windows:**
```json
{
  "servers": {
    "docx-reader": {
      "command": "node",
      "args": ["C:\\src\\docx-mcp-server\\dist\\index.js"]
    }
  }
}
```

**macOS / Linux:**
```json
{
  "servers": {
    "docx-reader": {
      "command": "node",
      "args": ["/home/you/docx-mcp-server/dist/index.js"]
    }
  }
}
```

Replace the path with the actual location where you cloned the repo.

## Configure in VS Code

Add to your `.vscode/mcp.json` (workspace) or user settings:

**Windows:**
```json
{
  "servers": {
    "docx-reader": {
      "command": "node",
      "args": ["C:\\src\\docx-mcp-server\\dist\\index.js"]
    }
  }
}
```

**macOS / Linux:**
```json
{
  "servers": {
    "docx-reader": {
      "command": "node",
      "args": ["/home/you/docx-mcp-server/dist/index.js"]
    }
  }
}
```

## Available Tools

### `resolve_document`

Finds `.docx` files by friendly name — the core of the natural language experience. Say "the report on my desktop" and it figures out which file you mean.

| Parameter  | Type   | Required | Description                          |
| ---------- | ------ | -------- | ------------------------------------ |
| `name`     | string | yes      | Friendly document name, with or without `.docx` extension (e.g., `"report"`, `"cloud architecture"`) |
| `location` | string | no       | Where to look: `"desktop"`, `"downloads"`, `"documents"`, `"current"`, or an absolute/relative path. Omit to search all common locations. |

### `read_document`

Reads a `.docx` file and returns the full text content.

| Parameter | Type   | Required | Description                          |
| --------- | ------ | -------- | ------------------------------------ |
| `path`    | string | yes      | Absolute or relative path to a `.docx` file |

### `search_document`

Searches for text within a `.docx` file and returns matching lines with context.

| Parameter | Type   | Required | Description                          |
| --------- | ------ | -------- | ------------------------------------ |
| `path`    | string | yes      | Absolute or relative path to a `.docx` file |
| `query`   | string | yes      | Text to search for (case-insensitive) |

### `get_document_metadata`

Returns metadata about a `.docx` file including name, size, dates, and word/character counts.

| Parameter | Type   | Required | Description                          |
| --------- | ------ | -------- | ------------------------------------ |
| `path`    | string | yes      | Absolute or relative path to a `.docx` file |

### `list_documents`

Lists all `.docx` files in a directory.

| Parameter   | Type   | Required | Description                          |
| ----------- | ------ | -------- | ------------------------------------ |
| `directory` | string | yes      | Absolute or relative path to a directory |

## Example Usage

**Natural language (the point of this whole thing):**

- *"Summarize the cloud architecture doc on my desktop"*
- *"Search for 'authentication' in the API proposal I downloaded"*
- *"What Word documents are in my Downloads?"*
- *"Open the RFP and tell me the deadline"*

**Explicit paths (if you really want to):**

- *"Read C:/docs/spec.docx and summarize it"*
- *"Search for 'budget' in /Users/me/Documents/report.docx"*

## Requirements

- Node.js ≥ 18
- Works on Windows, macOS, and Linux

## License

MIT