Metadata-Version: 2.4
Name: rvce-report-mcp
Version: 0.1.0
Summary: MCP server for generating RVCE Experiential Learning and Project reports as formatted .docx files
Project-URL: Homepage, https://github.com/your-username/rvce-report-mcp
Project-URL: Repository, https://github.com/your-username/rvce-report-mcp
Project-URL: Issues, https://github.com/your-username/rvce-report-mcp/issues
Author-email: Your Name <you@email.com>
License: MIT License
        
        Copyright (c) 2025 GongRzhe
        
        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.
License-File: LICENSE
Keywords: document-generation,docx,experiential-learning,fastmcp,mcp,report,rvce,word
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Education
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: Office Suites
Classifier: Topic :: Text Processing :: Markup
Requires-Python: >=3.11
Requires-Dist: fastmcp>=2.8.1
Requires-Dist: lxml>=4.9.0
Requires-Dist: python-docx>=1.1.2
Requires-Dist: python-dotenv>=1.0.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Description-Content-Type: text/markdown

# rvce-report-mcp

An [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) server that generates **RVCE Experiential Learning (EL)** and **VTU Project Reports** as properly formatted `.docx` files — directly from your AI assistant.

Attach your project folder to GitHub Copilot (or any MCP-compatible client), paste your TOC, and the LLM extracts content from your project files and builds the full report automatically.

---

## Features

- **Two-file output** — `report_pretoc.docx` (cover, certificate, declaration) + `report_main.docx` (abstract through references)
- **Format extraction** — reads a sample RVCE `.docx` template and replicates its exact heading styles, fonts, margins, header/footer rules
- **Auto Table of Contents** — inserts a real Word `{ TOC }` field; press `Ctrl+A → F9` to populate page numbers
- **Figure & table cross-references** — auto-generates `Figure X.Y` / `Table X.Y` labels and appends `(see Figure X.Y)` to the preceding paragraph
- **List of Figures / List of Tables** — built automatically from registered figures and tables
- **Bold keyword highlighting** — terms from `bold_keywords` (or the EL topic name) are auto-bolded throughout body text
- **Filename italicisation** — file/path tokens in body text are auto-italicised
- **Strict validation** — catches missing fields, short paragraphs, emoji in text, malformed references, and table column mismatches _before_ building
- **Personal reflection entries** — structured per-student reflection blocks with bold name + italic text
- **Supports `el_report` and `project_report`** format profiles (VTU CHAPTER-prefix style)
- **Three transports** — `stdio` (default), `streamable-http`, `sse`

---

## Requirements

- Python ≥ 3.11
- A pre-TOC Word template (`pre_toc_template.docx`) with the token placeholders listed below — place it at `rvce_report_mcp/assets/pre_toc_template.docx`

---

## Install

```bash
pip install rvce-report-mcp
```

Or for local development:

```bash
git clone https://github.com/your-username/rvce-report-mcp
cd rvce-report-mcp
pip install -e ".[dev]"
```

---

## MCP Client Configuration

### VS Code (GitHub Copilot Agent mode)

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

```json
{
  "mcp": {
    "servers": {
      "rvce-report-generator": {
        "type": "stdio",
        "command": "rvce-report-mcp",
        "env": {
          "MCP_TRANSPORT": "stdio"
        }
      }
    }
  }
}
```

### Claude Desktop

```json
{
  "mcpServers": {
    "rvce-report-generator": {
      "command": "rvce-report-mcp",
      "env": {
        "MCP_TRANSPORT": "stdio"
      }
    }
  }
}
```

### HTTP / SSE transport

```bash
RVCE_MCP_TRANSPORT=streamable-http RVCE_MCP_PORT=8001 rvce-report-mcp
```

---

## Usage

In Copilot Agent mode (or any MCP client):

1. Attach your project folder
2. Paste your desired TOC structure
3. Say: **"Generate my EL report using this TOC"**

The LLM will read your project files, build the `project_context` JSON, and call the tools in order.

### Recommended call order

```
inspect_pretoc_template → generate_pretoc_pages → create_rvce_report
```

After the files are created, open `report_main.docx` in Word and press **`Ctrl+A` → `F9`** to populate the Table of Contents page numbers.

---

## Available Tools

| Tool | Description |
|---|---|
| `read_template` | Extract a `FormatProfile` (heading styles, margins, header/footer) from a sample RVCE `.docx` |
| `inspect_template` | Paragraph-by-paragraph dump of any `.docx` — use to verify what `read_template` will detect |
| `inspect_pretoc_template` | List all `[token]` placeholders in the pre-TOC template. Call this **first** |
| `generate_pretoc_pages` | Fill the pre-TOC template with project details → `report_pretoc.docx` |
| `get_rvce_format_profile` | Return the built-in formatting defaults as JSON (no template required) |
| `create_rvce_report` | Build the full report (abstract → TOC → chapters → references) → `report_main.docx` |
| `inspect_report` | Paragraph-by-paragraph dump of a generated report — use to verify output |
| `add_report_section` | Replace or append a named section (`abstract`, `acknowledgement`, `chapter_N`, `references`, `appendix`) in an existing `.docx` |

---

## `project_context` Schema

```json
{
  "report_type": "el_report",
  "project_title": "string — required",
  "sdg_theme": "SDG 9 - Industry, Innovation and Infrastructure",
  "college_name": "RV College of Engineering",
  "academic_year": "2025-26",
  "semester": "V",
  "faculty_mentor": {
    "name": "string — required",
    "designation": "string",
    "department": "string"
  },
  "abstract": "string — 150-250 words",
  "el_topic": "string — EL topic name (used in header and as bold keyword)",
  "bold_keywords": ["keyword1", "keyword2"],
  "team": [
    {"name": "string", "usn": "string", "dept": "string", "email": "string"}
  ],
  "chapters": [
    {
      "number": 1,
      "title": "string",
      "sections": [
        {
          "heading": "1.1 Section Title",
          "paragraphs": [
            {"type": "body", "text": "string — min 40 words"},
            {"type": "bullet_list", "items": ["item 1", "item 2"]},
            {"type": "numbered_list", "items": ["step 1", "step 2"]},
            {"type": "figure", "id": "fig_unique_id", "caption": "string", "source": "screenshot"},
            {"type": "table", "id": "tbl_unique_id", "caption": "string",
             "headers": ["Col 1", "Col 2"], "rows": [["val", "val"]]},
            {"type": "personal_reflection", "entries": [
              {"name": "Student Name", "text": "reflection text"}
            ]}
          ],
          "subsections": []
        }
      ]
    }
  ],
  "appendix": {
    "title": "Visuals",
    "paragraphs": [
      {"type": "figure", "id": "fig_appendix", "caption": "string", "source": "screenshot"}
    ]
  },
  "references": [
    "1. A. Author, \"Title,\" Journal, vol. 1, pp. 1-10, 2024."
  ]
}
```

### Paragraph rules

- Every section requires **minimum 3 paragraph objects** (body, list, figure, and table all count)
- Body paragraphs require **minimum 40 words**
- First and last paragraph of each section must be `type: body`
- Figure and table `id` values must be **unique across the entire document**
- Table `headers` column count must match every row in `rows`
- `col_widths` (optional) must sum to exactly `100`
- Maximum **5 team members** in the pre-TOC template
- Minimum **5 references**
- No emoji in any text field

### Figure `source` values

| Value | Behaviour |
|---|---|
| `napkin` | Grey placeholder with Napkin export instructions |
| `draw.io` | Grey placeholder with draw.io export instructions |
| `screenshot` | Grey placeholder for screenshot |
| `image_file` | Grey placeholder for generic image |
| `embed` | Embeds the actual image from `file_path` |

---

## Pre-TOC Template Tokens

Place `pre_toc_template.docx` in `rvce_report_mcp/assets/`. The following tokens are replaced at build time:

| Token | Replaced with |
|---|---|
| `[project_title]` | `project_context.project_title` |
| `[theme]` | `project_context.sdg_theme` |
| `[team_member_name_1]` … `[team_member_name_5]` | Team member names |
| `[usn_1]` … `[usn_5]` | Team member USNs |
| `[mentor_name]` | `faculty_mentor.name` |
| `[mentor_designation]` | `faculty_mentor.designation` |
| `[mentor_dept]` | `faculty_mentor.department` |
| `[today's date]` | Current date (`dd Month YYYY`) |
| `2025-26` | `academic_year` short form |
| `2025-2026` | `academic_year` long form |

---

## Environment Variables

| Variable | Default | Description |
|---|---|---|
| `RVCE_MCP_TRANSPORT` | `stdio` | Transport type: `stdio`, `streamable-http`, `sse` |
| `RVCE_MCP_HOST` | `0.0.0.0` | Host for HTTP/SSE transport |
| `RVCE_MCP_PORT` | `8001` | Port for HTTP/SSE transport |
| `RVCE_MCP_PATH` | `/mcp` | Path for streamable-http transport |
| `RVCE_MCP_SSE_PATH` | `/sse` | Path for SSE transport |
| `RVCE_MCP_DEBUG` | `false` | Enable debug logging |

---

## Project Structure

```
rvce_report_mcp/
├── main.py                  # FastMCP server entry point, tool registration
├── assets/
│   └── pre_toc_template.docx  # Place your RVCE template here
├── core/
│   ├── __init__.py          # FormatProfile, HeaderProfile, FooterProfile dataclasses
│   ├── cross_reference.py   # FigureRegistry, TableRegistry
│   ├── format_extractor.py  # Extracts FormatProfile from a sample DOCX
│   ├── page_setup.py        # Page margins, header/footer builder
│   ├── placeholder.py       # Grey figure placeholder boxes
│   ├── report_builder.py    # Full document orchestrator
│   └── token_extractor.py   # Extracts [tokens] from template XML
├── tools/
│   ├── report_tools.py      # generate_pretoc_pages, create_rvce_report, inspect_report
│   ├── section_tools.py     # add_report_section
│   └── template_tools.py    # read_template, inspect_template
└── utils/
    ├── style_utils.py       # apply_paragraph_format, column width helpers
    ├── toc_utils.py         # TOC, LoF, LoT builders
    └── validator.py         # project_context validation
```

---

## License

MIT — see [LICENSE](LICENSE).