eimmig/sprint-docx-mcp-server

Sprint DOCX MCP Server

A GitHub Copilot agent that processes DOCX Sprint documents with hierarchical structure (Sprint → Stories → Subtasks) and generates Jira-formatted markdown files.

Overview

This GitHub Copilot agent enables you to:

• Analyze DOCX Sprint documents and understand their hierarchical structure
• Generate individual Jira-formatted Markdown files for each Sprint, Story, and Subtask
• Process specific Sprints selectively for targeted workflows
• Extract complete content including descriptions, acceptance criteria, and scenarios

Features

🤖 GitHub Copilot Integration

Use natural language commands in Copilot:

• "Analyze my Sprint DOCX document structure"
• "Generate markdown files for all sprints"
• "Process only the first sprint"

🔍 Three MCP Tools

1. analyze_sprint_document - Parse and analyze DOCX structure, returns JSON hierarchy
2. generate_sprint_files - Generate all Markdown files from DOCX with Jira formatting
3. process_single_sprint - Process a single Sprint by index (0-based)

📝 Jira-Formatted Output

Generated markdown files use Jira markup for better readability:

• h1., h2., h3. headers for structure
• Colored bullets for Given/When/Then scenarios
• Emphasized user stories with *text*
• Horizontal separators with ----

📄 Document Structure Support

The server recognizes these patterns in DOCX files:

• Sprint sections: Sprint X.X (e.g., "Sprint 1.1", "Sprint 2.3")
• Story sections: Contains keywords like "User Story", "História de Usuário", "Como uma"
• Subtask sections: Tarefa X.X.X (e.g., "Tarefa 1.1.1", "Tarefa 2.3.4")
• Acceptance criteria: "Critérios de Aceite", "Cenários"
• Scenarios: "Dado que", "Quando", "Então" (Given/When/Then)

Installation

As a GitHub Copilot Agent

# Install globally
npm install -g sprint-docx-mcp-server

The agent.json will automatically register the agent with GitHub Copilot.

For Development

# Install dependencies
npm install

# Build the project
npm run build

# Watch mode for development
npm run dev

Configuration

VS Code Setup (MCP Server Mode)

Add to your .vscode/mcp.json:

{
  "mcpServers": {
    "sprint-docx-processor": {
      "command": "sprint-docx-mcp-server"
    }
  }
}

Claude Desktop Setup

Add to claude_desktop_config.json:

Windows (Development):

{
  "mcpServers": {
    "sprint-docx-processor": {
      "command": "node",
      "args": ["d:\\UTFPR\\TCC\\AI Sprint Manager\\build\\index.js"]
    }
  }
}

Global Installation:

{
  "mcpServers": {
    "sprint-docx-processor": {
      "command": "sprint-docx-mcp-server"
    }
  }
}

Usage

With GitHub Copilot in VS Code

After installing the agent, use the conversation starters or natural language:

Using Conversation Starters:

• Click "Analyze my Sprint DOCX document structure"
• Click "Generate markdown files for all sprints"
• Click "Process only the first sprint"

Using Natural Language:

Analyze the Sprint document at C:/projects/sprints.docx

Generate markdown files for all Sprints from C:/projects/sprints.docx, 
save to C:/output, using templates from C:/projects/templates

Process only Sprint 0 from C:/projects/sprints.docx and save to C:/output

Tool Parameters

1. analyze_sprint_document

Returns JSON hierarchy of your Sprint document.

Parameters:

{
  "docxPath": "C:/path/to/sprints.docx"
}

Output Example:

[
  {
    "number": "1.0",
    "title": "User Authentication",
    "content": "Sprint description...",
    "stories": [
      {
        "number": "1.1.0",
        "title": "Login Page",
        "content": "Como uma usuário...",
        "subtasks": [
          {
            "number": "1.1.1",
            "title": "Design Login UI",
            "content": "Projeto: Frontend..."
          }
        ]
      }
    ]
  }
]

2. generate_sprint_files

Generates all markdown files with Jira formatting.

Parameters:

{
  "docxPath": "C:/path/to/sprints.docx",
  "outputDir": "C:/output",
  "templatesDir": "C:/templates",
  "filePrefix": "project_"  // optional
}

Output: Creates files like:

• project_sprint_1.md - Sprint overview with story list
• project_story_1_1.md - Story with formatted content
• project_subtask_1_1_1.md - Subtask with checklist

3. process_single_sprint

Processes one sprint by index (0-based).

Parameters:

{
  "docxPath": "C:/path/to/sprints.docx",
  "sprintIndex": 0,  // 0 for first sprint, 1 for second, etc.
  "outputDir": "C:/output",
  "templatesDir": "C:/templates",
  "filePrefix": "sprint1_"  // optional
}

Use Case: Process sprints incrementally or reprocess specific sprints after changes.

Document Structure Requirements

Your DOCX document should follow this hierarchical pattern:

Sprint 1.0 - Sprint Title
  Descrição do sprint...

  Story 1.1.0 - Story Title
    Como uma [persona]...
    
    Critérios de Aceite
    - Critério 1
    - Critério 2
    
    Cenários:
      Dado que [precondição]
      Quando [ação]
      Então [resultado esperado]
    
    Sub-Tarefas:
    
    Tarefa 1.1.1 - Subtask Title
      Projeto: [project name]
      Tipo: [task type]
      Descrição: [description]
      Passo-a-passo:
        1. First step
        2. Second step
        3. Third step
    
    Tarefa 1.1.2 - Another Subtask
      ...

  Story 1.2.0 - Another Story
    ...

Sprint 2.0 - Next Sprint
  ...

Generated File Structure

Sprint File (sprint_1.md)

h1. Sprint 1.0 - User Authentication

h2. Informações Gerais
* *Sprint:* 1
* *Total Stories:* 3

h2. Stories
* story_1_1.md - Login Page
* story_1_2.md - Registration Form
* story_1_3.md - Password Recovery

----

Story File (story_1_1.md)

h1. Story 1.1.0 - Login Page

h2. Descrição

*Como uma usuário do sistema*
*Eu quero fazer login com email e senha*
*Para que possa acessar minha conta*

h3. Critérios de Aceite
* Campo de email validado
* Campo de senha com máscara
* Botão de login habilitado apenas com dados válidos

h3. Cenários

h3. Cenário 1: Login com sucesso
* {color:#00875a}✓{color} Dado que estou na página de login
* {color:#0052cc}→{color} Quando insiro credenciais válidas
* {color:#6554c0}✓{color} Então sou redirecionado para o dashboard

----

h2. Sub-Tarefas
* subtask_1_1_1.md - Design Login UI
* subtask_1_1_2.md - Implement Authentication Logic

Subtask File (subtask_1_1_1.md)

h1. Tarefa 1.1.1 - Design Login UI

h2. Informações
* *Projeto:* Frontend
* *Tipo:* Design

h2. Descrição
Criar interface de login responsiva com validação

h2. Passo-a-passo
- [ ] Criar wireframe da tela
- [ ] Definir paleta de cores
- [ ] Implementar layout responsivo
- [ ] Adicionar validação de formulário

Template Files

Create three template files in your templates directory:

sprint.md

h1. {sprint_title}

h2. Informações Gerais
* *Sprint:* {sprint_number}
* *Total Stories:* {story_count}

h2. Stories
{stories_list}

----

story.md

h1. {story_title}

h2. Descrição
{story_content}

h2. Sub-Tarefas
{subtasks_list}

----

subtask.md

h1. {subtask_title}

h2. Descrição
{subtask_content}

Jira Formatting Reference

File Naming Convention

Generated files follow this pattern:

{filePrefix}sprint_{N}.md
{filePrefix}story_{N}_{M}.md
{filePrefix}subtask_{N}_{M}_{P}.md

Where:

• N = Sprint number (1, 2, 3...)
• M = Story number within sprint (1, 2, 3...)
• P = Subtask number within story (1, 2, 3...)

Example output structure:

output/
├── sprint_1.md
├── story_1_1.md
├── story_1_2.md
├── subtask_1_1_1.md
├── subtask_1_1_2.md
├── subtask_1_2_1.md
├── sprint_2.md
├── story_2_1.md
└── ...

Development

Project Structure

sprint-docx-mcp-server/
├── src/
│   ├── index.ts              # MCP server & tool definitions
│   ├── docx-reader.ts        # DOCX parsing with content extraction
│   ├── template-processor.ts # Jira formatting & template processing
│   └── file-generator.ts     # File generation with unique naming
├── build/                    # Compiled JavaScript (ES modules)
├── agent.json                # GitHub Copilot agent configuration
├── .vscode/
│   └── mcp.json             # VS Code MCP configuration
├── templates/
│   ├── sprint.md            # Sprint template
│   ├── story.md             # Story template
│   └── subtask.md           # Subtask template
├── package.json
├── tsconfig.json
└── README.md

Build Commands

# Watch mode for development
npm run dev

# Build for production
npm run build

# Prepare for publishing (auto-runs on install)
npm run prepare

Technology Stack

• TypeScript 5.7+ - Type-safe development with ES modules
• MCP SDK 1.0.4 - Model Context Protocol integration
• mammoth 1.8.0 - DOCX text extraction
• zod 3.23.8 - Schema validation for tool parameters
• Node.js 18+ - Runtime environment

Troubleshooting

Agent not appearing in Copilot

1. Ensure global installation: npm install -g sprint-docx-mcp-server
2. Verify agent.json exists in the package root
3. Restart VS Code completely

Empty content in generated files

• Verify DOCX follows the hierarchical structure (Sprint → Story → Subtask)
• Check that stories contain keywords: "Como uma", "Critérios de Aceite"
• Ensure subtasks are labeled with "Tarefa X.X.X"

Filename collisions (files overwriting)

• Use the filePrefix parameter to add unique prefixes
• Process sprints individually with process_single_sprint

Template not found errors

• Verify sprint.md, story.md, subtask.md exist in templatesDir
• Use absolute paths for templatesDir parameter

Windows path issues

• Use forward slashes: C:/path/to/file.docx
• Or escape backslashes: C:\\path\\to\\file.docx
• Always provide absolute paths in tool parameters

Build errors

# Reinstall dependencies
npm install

# Clear build directory
Remove-Item -Recurse -Force build; npm run build

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

MIT License - see LICENSE file for details

Author

UTFPR TCC Project

Support

• Issues: https://github.com/eimmig/sprint-docx-mcp-server/issues
• Documentation: https://github.com/eimmig/sprint-docx-mcp-server#readme

Changelog

1.0.0 (Current)

• ✅ GitHub Copilot agent integration with agent.json
• ✅ Three MCP tools: analyze, generate_all, process_single
• ✅ Full content extraction from DOCX (sprints, stories, subtasks)
• ✅ Jira formatting with colored bullets and headers
• ✅ Unique file naming with sprint-based numbering
• ✅ Template system for customizable output
• ✅ Support for hierarchical Sprint/Story/Subtask structure
• ✅ Windows and cross-platform compatibility npm run build

### DOCX parsing issues

- Verify DOCX file path is absolute
- Check DOCX file isn't corrupted
- Ensure document follows expected structure patterns

## Migration from Python Implementation

This TypeScript MCP server replaces the original Python + Gemini API implementation:

| **Python (Old)** | **TypeScript MCP (New)** |
|------------------|--------------------------|
| Direct Gemini API calls | Uses Copilot (no API quotas) |
| Limited by API rate limits | No external API limitations |
| Standalone script | MCP server (integrates with tools) |
| Manual execution | Natural language interface |

The core hierarchical processing logic remains the same, but the interface has evolved to leverage MCP's capabilities.

## License

MIT

## Contributing

Contributions welcome! Please feel free to submit issues or pull requests.