# Proplist MCP Hello World

Minimal FastMCP server that proves this integration path:

```text
MCP Client -> FastMCP Server -> Microsoft Graph -> SharePoint Excel Workbook
```

The server exposes one MCP tool, `list_worksheets`, which returns worksheet names, worksheet IDs, and visibility states from an existing Excel workbook stored in SharePoint.

This milestone intentionally does not create workbook sessions, read cell ranges, parse natural language, or interpret proposal data.

## Project Tree

```text
proplist-mcp-helloworld/
├── server.py
├── pyproject.toml
├── .env.example
├── .gitignore
└── README.md
```

## Configuration

Create a local `.env` file from `.env.example`:

```bash
cp .env.example .env
```

Set every value:

```text
TENANT_ID=...
CLIENT_ID=...
CLIENT_SECRET=...
DRIVE_ID=...
ITEM_ID=...
```

- `TENANT_ID`: Microsoft Entra tenant identifier.
- `CLIENT_ID`: application registration client identifier.
- `CLIENT_SECRET`: application registration client secret.
- `DRIVE_ID`: Microsoft Graph drive identifier containing the workbook.
- `ITEM_ID`: Microsoft Graph item identifier for the workbook.

Do not commit `.env`. It is excluded by `.gitignore`.

## Microsoft Graph Permission

The app registration must have this Microsoft Graph application permission:

```text
Files.Read.All
```

Tenant admin consent must be granted outside this code. A `403 Forbidden` response usually means the app can authenticate but does not have the required application permission or admin consent.

## Install And Validate

```bash
uv sync
uv run python -m py_compile server.py
```

You can start the stdio server with either command:

```bash
uv run server.py
uv run proplist-mcp
```

To inspect the MCP server:

```bash
npx @modelcontextprotocol/inspector uv run server.py
```

Then call the `list_worksheets` tool in the Inspector.

## Expected Tool Output

When the credentials and workbook identifiers are valid, the tool returns Markdown:

```markdown
## Worksheets

| Name | Worksheet ID | Visibility |
|---|---|---|
| Proposals | {...} | Visible |
| Lookup | {...} | Hidden |
```

Do not treat this sample as proof that your workbook is reachable. The integration is live only when the tool returns real worksheet metadata from your configured workbook.

## Risks And Troubleshooting

| Risk | Treatment |
| --- | --- |
| Missing Graph permission | Add Microsoft Graph `Files.Read.All` as an application permission and grant tenant admin consent. |
| Incorrect `DRIVE_ID` or `ITEM_ID` | The tool returns a `404 Not Found` explanation. Verify the drive and item identifiers in Microsoft Graph. |
| Expired client secret | Replace `CLIENT_SECRET` in Microsoft Entra ID and update the local `.env` file. |
| Secret leakage | Keep `.env` out of Git. This project `.gitignore` excludes it. |
| Graph throttling | The tool surfaces `429 Too Many Requests` and includes `Retry-After` when Graph provides it. |
| Untested credentials | `uv sync` and `py_compile` validate code only. Live integration validation requires real credentials and real worksheet metadata. |

## Known Scope Limits

- Uses OAuth 2.0 client credentials only.
- Uses Microsoft Graph app-only access only.
- Does not use delegated, interactive browser, device-code, or username/password authentication.
- Does not call `workbook/createSession`.
- Does not read workbook ranges or tables.
- Does not add storage, LLM calls, LangChain, LangGraph, agents, web UI, Docker, CI/CD, Key Vault, or telemetry.