### Verify Setup

Source: https://github.com/demodorigatsuo/sharepoint-mcp/blob/main/README.md

Optionally, run these scripts to validate your configuration and test authentication before starting the server.

```bash
python config_checker.py   # Validate configuration
python auth-diagnostic.py  # Test authentication
```

--------------------------------

### Example Prompt: Multi-step Workflow for Project Setup

Source: https://github.com/demodorigatsuo/sharepoint-mcp/blob/main/docs/usage.md

A multi-step prompt to automate the setup of a new project area in SharePoint, including site creation, list and library setup, and page publishing.

```text
Set up a new project area in SharePoint:
1. Create a site called "Product Launch" with alias "productlaunch"
2. Add a tasks list with status, priority, and due date fields
3. Create a document library for project documents
4. Create a welcome page introducing the project
```

--------------------------------

### Example Prompt: Get Site ID and Create List

Source: https://github.com/demodorigatsuo/sharepoint-mcp/blob/main/docs/usage.md

Demonstrates a multi-step workflow where site information is first retrieved to obtain a site ID, which is then used to create a new tasks list.

```text
First get information about my SharePoint site, then use the site ID to create a new tasks list.
```

--------------------------------

### Clone and Install Dependencies

Source: https://github.com/demodorigatsuo/sharepoint-mcp/blob/main/README.md

Clone the repository and install the required Python packages. Activate the virtual environment before installing.

```bash
git clone https://github.com/DEmodoriGatsuO/sharepoint-mcp.git
cd sharepoint-mcp

python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

pip install -r requirements.txt
```

--------------------------------

### Steering Directory Naming Convention Examples

Source: https://github.com/demodorigatsuo/sharepoint-mcp/blob/main/Claude.md

Examples of how to name steering directories for development tasks, including a date and a descriptive title.

```bash
mkdir -p .steering/[YYYYMMDD]-initial-implementation

```

```bash
mkdir -p .steering/20250103-initial-implementation/

```

```bash
.steering/20250115-add-tag-feature/

```

```bash
.steering/20250120-fix-filter-bug/

```

```bash
.steering/20250201-improve-performance/

```

--------------------------------

### Install Server into Claude Desktop

Source: https://github.com/demodorigatsuo/sharepoint-mcp/blob/main/README.md

Install the server directly into Claude Desktop using the mcp command or by manually adding its configuration to the `claude_desktop_config.json` file.

```bash
mcp install server.py --name "SharePoint Assistant"
```

```json
{
  "mcpServers": {
    "sharepoint": {
      "command": "python",
      "args": ["/absolute/path/to/sharepoint-mcp/server.py"],
      "env": {
        "TENANT_ID": "...",
        "CLIENT_ID": "...",
        "CLIENT_SECRET": "...",
        "SITE_URL": "..."
      }
    }
  }
}
```

--------------------------------

### Start HTTP Server with Specific Transport and Port

Source: https://github.com/demodorigatsuo/sharepoint-mcp/blob/main/README.md

Configure and start the HTTP server using streamable-http or SSE. You can specify the host and port, or use environment variables.

```bash
# streamable-http (recommended for Copilot agents and web clients)
python server.py --transport streamable-http --host 0.0.0.0 --port 8000

# SSE
python server.py --transport sse --host 0.0.0.0 --port 8000

# Via environment variables
MCP_TRANSPORT=streamable-http MCP_PORT=8000 python server.py
```

--------------------------------

### Create Steering Directory for Initial Implementation

Source: https://github.com/demodorigatsuo/sharepoint-mcp/blob/main/Claude.md

Command to create the initial steering directory for the project setup.

```bash
mkdir -p .steering/[YYYYMMDD]-initial-implementation

```

--------------------------------

### Start SharePoint MCP Server

Source: https://github.com/demodorigatsuo/sharepoint-mcp/blob/main/README.md

Start the server using different transport methods. The default is stdio. For web services, use streamable-http. Docker is also supported.

```bash
# stdio — default, for Claude Desktop / MCP Inspector
python server.py

# HTTP streamable-http — for web services and Copilot agents
python server.py --transport streamable-http --port 8000

# Docker
docker-compose up
```

--------------------------------

### Example Prompt: Create SharePoint Site

Source: https://github.com/demodorigatsuo/sharepoint-mcp/blob/main/docs/usage.md

A prompt to provision a new SharePoint team site with a display name and alias.

```text
Create a new SharePoint site for our Marketing team with the alias "marketing".
```

--------------------------------

### Example Prompt: Get Document Content

Source: https://github.com/demodorigatsuo/sharepoint-mcp/blob/main/docs/usage.md

A prompt to read and retrieve the content of a specific document from a SharePoint library.

```text
Can you read the contents of "sales_data.xlsx" from my Reports library?
```

--------------------------------

### Pytest Example: Mocking HTTP GET Request

Source: https://github.com/demodorigatsuo/sharepoint-mcp/blob/main/docs/development-guidelines.md

Demonstrates how to write an asynchronous test using 'pytest' and 'unittest.mock.patch' to mock an external HTTP GET request. This ensures unit tests do not make real network calls.

```python
async def test_get(graph_client):
    with patch("requests.get") as mock_get:
        mock_get.return_value.status_code = 200
        mock_get.return_value.json.return_value = {"value": "data"}
        result = await graph_client.get("endpoint/test")
        assert result == {"value": "data"}
```

--------------------------------

### Example Prompt: List Document Libraries

Source: https://github.com/demodorigatsuo/sharepoint-mcp/blob/main/docs/usage.md

A prompt to query the available document libraries on a SharePoint site.

```text
What document libraries are available on my SharePoint site?
```

--------------------------------

### Install Development Dependencies

Source: https://github.com/demodorigatsuo/sharepoint-mcp/blob/main/CONTRIBUTING.md

Installs the project's development dependencies using pip. This command ensures all necessary tools for development are available in the virtual environment.

```bash
pip install -e ".[dev]"
```

--------------------------------

### Configure Environment Variables

Source: https://github.com/demodorigatsuo/sharepoint-mcp/blob/main/README.md

Copy the example environment file and edit it with your Azure AD credentials and SharePoint site URL. Ensure all required variables are provided.

```bash
cp .env.example .env
# Edit .env with your Azure AD credentials and SharePoint site URL
```

--------------------------------

### Install SharePoint MCP Server in Claude Desktop

Source: https://github.com/demodorigatsuo/sharepoint-mcp/blob/main/docs/architecture.md

Installs the SharePoint MCP Server for use within Claude Desktop, assigning it a specific name.

```bash
mcp install server.py --name "SharePoint Assistant"
```

--------------------------------

### Run SharePoint MCP Server (stdio)

Source: https://github.com/demodorigatsuo/sharepoint-mcp/blob/main/docs/architecture.md

Starts the MCP server using the standard input/output transport, which is the default.

```bash
python server.py
```

--------------------------------

### Start SharePoint MCP Server (HTTP)

Source: https://github.com/demodorigatsuo/sharepoint-mcp/blob/main/docs/usage.md

Starts the SharePoint MCP Server with HTTP transport on a specified port, intended for web services and Copilot agents.

```bash
python server.py --transport streamable-http --port 8000
```

--------------------------------

### Example Prompt: List List Items

Source: https://github.com/demodorigatsuo/sharepoint-mcp/blob/main/docs/usage.md

A prompt to retrieve all items from a specified SharePoint list.

```text
Show me all items in the "Tasks" list on my SharePoint site.
```

--------------------------------

### Example Prompt: Create Intelligent List

Source: https://github.com/demodorigatsuo/sharepoint-mcp/blob/main/docs/usage.md

A prompt to create a new SharePoint list with an AI-optimized schema for a specific purpose.

```text
Create a "Projects" list called "Marketing Projects" with fields for status, priority, and due dates.
```

--------------------------------

### Example Prompt: Create Document Library

Source: https://github.com/demodorigatsuo/sharepoint-mcp/blob/main/docs/usage.md

A prompt to create a new document library in SharePoint with a specified name and document type for metadata.

```text
Create a document library called "Legal Documents" for contracts with appropriate metadata fields.
```

--------------------------------

### Run SharePoint MCP Server (SSE)

Source: https://github.com/demodorigatsuo/sharepoint-mcp/blob/main/docs/architecture.md

Starts the MCP server using the Server-Sent Events (SSE) transport.

```bash
python server.py --transport sse --host 0.0.0.0 --port 8000
```

--------------------------------

### Example Prompt: Create Modern Page

Source: https://github.com/demodorigatsuo/sharepoint-mcp/blob/main/docs/usage.md

A prompt to publish a new modern SharePoint page with a given name, purpose, and audience.

```text
Create a welcome page called "home" for our team site.
```

--------------------------------

### Example Prompt: Search SharePoint

Source: https://github.com/demodorigatsuo/sharepoint-mcp/blob/main/docs/usage.md

A prompt to perform a full-text search for specific documents within a SharePoint site.

```text
Search my SharePoint site for documents related to "quarterly revenue".
```

--------------------------------

### Run SharePoint MCP Server (streamable-http)

Source: https://github.com/demodorigatsuo/sharepoint-mcp/blob/main/docs/architecture.md

Starts the MCP server using the streamable-http transport. Can be configured via command-line arguments or environment variables.

```bash
python server.py --transport streamable-http --host 0.0.0.0 --port 8000
```

```bash
MCP_TRANSPORT=streamable-http MCP_PORT=8000 python server.py
```

--------------------------------

### Example Prompt: Analyze Document

Source: https://github.com/demodorigatsuo/sharepoint-mcp/blob/main/docs/usage.md

A prompt to analyze a document and summarize its key information.

```text
Analyze the "project_plan.docx" file and summarize the key milestones.
```

--------------------------------

### Example Prompt: Create List Item

Source: https://github.com/demodorigatsuo/sharepoint-mcp/blob/main/docs/usage.md

A prompt to create a new item within a SharePoint list with specified details.

```text
Create a new task in the "Tasks" list with the title "Prepare monthly report" and status "Not Started".
```

--------------------------------

### Example Prompt: List Folder Contents

Source: https://github.com/demodorigatsuo/sharepoint-mcp/blob/main/docs/usage.md

A prompt to display files and subfolders within a specified path in a SharePoint document library.

```text
Show me all files in the "Reports/2026" folder of the "Shared Documents" library.
```

--------------------------------

### Example Prompt: Update List Item

Source: https://github.com/demodorigatsuo/sharepoint-mcp/blob/main/docs/usage.md

A prompt to modify an existing item in a SharePoint list, updating its fields.

```text
Update item 42 in the "Projects" list and set the status to "Completed".
```

--------------------------------

### Run SharePoint MCP Server with Docker

Source: https://github.com/demodorigatsuo/sharepoint-mcp/blob/main/README.md

Build the Docker image and start the container. The default configuration uses streamable-http on port 8000. You can also use an environment file for configuration.

```bash
# Build and start (defaults to streamable-http on port 8000)
docker-compose up

# Or run manually
docker build -t sharepoint-mcp .
docker run --env-file .env -p 8000:8000 sharepoint-mcp
```

--------------------------------

### Run SharePoint MCP Server with Docker Compose

Source: https://github.com/demodorigatsuo/sharepoint-mcp/blob/main/docs/architecture.md

Starts the SharePoint MCP Server using Docker Compose, which loads credentials from .env and exposes port 8000.

```bash
docker-compose up
```

--------------------------------

### Pytest Example: Avoiding Direct Boolean Comparisons

Source: https://github.com/demodorigatsuo/sharepoint-mcp/blob/main/docs/development-guidelines.md

Illustrates the correct way to check boolean conditions in tests, adhering to 'ruff E712' which advises against using '== True' or '== False'. Use direct truthiness checks instead.

```python
# Avoid
assert context.is_token_valid() == True   # ruff E712
assert context.is_token_valid() == False  # ruff E712

# Correct
assert context.is_token_valid()
assert not context.is_token_valid()
```

--------------------------------

### Set Up Virtual Environment

Source: https://github.com/demodorigatsuo/sharepoint-mcp/blob/main/CONTRIBUTING.md

Creates and activates a Python virtual environment for development. Use the appropriate command for your operating system.

```bash
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
```

--------------------------------

### Build and Run SharePoint MCP Server with Docker

Source: https://github.com/demodorigatsuo/sharepoint-mcp/blob/main/docs/architecture.md

Builds the Docker image for the SharePoint MCP Server and runs it, mapping port 8000 and loading environment variables from a .env file.

```bash
# Build the image
docker build -t sharepoint-mcp .

# Run with environment file
docker run --env-file .env -p 8000:8000 sharepoint-mcp
```

--------------------------------

### Run Quality Checks

Source: https://github.com/demodorigatsuo/sharepoint-mcp/blob/main/README.md

Execute formatting, linting, and testing checks for contributions. Ensure these commands pass before submitting changes.

```bash
black .
ruff check .
pytest
```

--------------------------------

### Run MCP Inspector for Development

Source: https://github.com/demodorigatsuo/sharepoint-mcp/blob/main/README.md

Use this command to run the server in development mode with the MCP Inspector.

```bash
mcp dev server.py
```

--------------------------------

### SharePoint MCP Desktop Configuration

Source: https://github.com/demodorigatsuo/sharepoint-mcp/blob/main/docs/architecture.md

This JSON file configures the connection details for a SharePoint MCP server, including the command to run, arguments, and environment variables for authentication and site URL.

```json
{
  "mcpServers": {
    "sharepoint": {
      "command": "python",
      "args": ["/path/to/sharepoint-mcp/server.py"],
      "env": {
        "TENANT_ID": "...",
        "CLIENT_ID": "...",
        "CLIENT_SECRET": "...",
        "SITE_URL": "..."
      }
    }
  }
}
```

--------------------------------

### Certificate-Based Authentication with MSAL (Python)

Source: https://github.com/demodorigatsuo/sharepoint-mcp/blob/main/docs/auth_guide.md

This Python snippet demonstrates how to use the MSAL library for confidential client authentication with certificate credentials. Ensure you have the private key, public certificate, and the correct certificate thumbprint from Azure Portal.

```python
import msal

# Read certificate
with open('key.pem', 'rb') as cert_file:
    private_key = cert_file.read()

with open('certificate.pem', 'rb') as cert_file:
    public_certificate = cert_file.read()

# Create client application
app = msal.ConfidentialClientApplication(
    CONFIG["client_id"],
    authority=f"https://login.microsoftonline.com/{CONFIG['tenant_id']}",
    client_credential={
        'private_key': private_key,
        'thumbprint': 'your-certificate-thumbprint',  # From Azure Portal
        'public_certificate': public_certificate
    }
)
```

--------------------------------

### Format and Lint Code

Source: https://github.com/demodorigatsuo/sharepoint-mcp/blob/main/CONTRIBUTING.md

Applies code formatting using Black and runs the linter using Ruff. These commands should be run before committing to ensure code quality and consistency.

```bash
# Format code
black src tests

# Run linter
ruff check src tests
```

--------------------------------

### Create Steering Directory for Feature Addition/Bug Fix

Source: https://github.com/demodorigatsuo/sharepoint-mcp/blob/main/Claude.md

Command to create a new steering directory for a specific development task, such as adding a feature or fixing a bug.

```bash
mkdir -p .steering/[YYYYMMDD]-[task-title]

```

```bash
# Example: mkdir -p .steering/20250115-add-tag-feature

```

--------------------------------

### MCP Server Configuration (.env file)

Source: https://github.com/demodorigatsuo/sharepoint-mcp/blob/main/docs/auth_guide.md

Update your .env file with your Azure AD application credentials and SharePoint site URL. Username and password are only needed for user-delegated authentication.

```dotenv
TENANT_ID=your_tenant_id_from_step_2
CLIENT_ID=your_client_id_from_step_2
CLIENT_SECRET=your_client_secret_from_step_3
SITE_URL=https://your-tenant.sharepoint.com/sites/your-site
USERNAME=your.email@example.com  # Only needed for user-delegated auth
PASSWORD=your_password           # Only needed for user-delegated auth
```

--------------------------------

### SharePoint MCP Use Case Diagram

Source: https://github.com/demodorigatsuo/sharepoint-mcp/blob/main/docs/functional-design.md

Illustrates the use cases for the SharePoint MCP, showing interactions between users, administrators, the MCP server, and the Microsoft Graph API.

```mermaid
graph LR
    User([Knowledge Worker]) --> UC1[Get Site Info]
    User --> UC2[Browse Libraries]
    User --> UC3[Search Content]
    User --> UC4[Read Document]
    User --> UC5[Create List Item]
    Admin([IT Admin / Developer]) --> UC6[Create Site]
    Admin --> UC7[Create List]
    Admin --> UC8[Create Page]
    Admin --> UC9[Upload Document]

    UC1 & UC2 & UC3 & UC4 & UC5 & UC6 & UC7 & UC8 & UC9 --> MCP[MCP Server]
    MCP --> Graph[Microsoft Graph API]
```

--------------------------------

### SharePoint MCP Tool Pattern

Source: https://github.com/demodorigatsuo/sharepoint-mcp/blob/main/docs/functional-design.md

Illustrates the standard pattern followed by all tools within the SharePoint MCP Server for interacting with the SharePoint API.

```text
1. Get SharePointContext from lifespan context
2. _check_auth() — raise if token is invalid
3. refresh_token_if_needed()
4. Instantiate GraphClient
5. Call Graph API method
6. Return JSON-serialized result
```

--------------------------------

### Generate Self-Signed Certificate

Source: https://github.com/demodorigatsuo/sharepoint-mcp/blob/main/docs/auth_guide.md

Use OpenSSL to generate a private key and a self-signed certificate for secure authentication. This is recommended for production environments.

```bash
openssl req -newkey rsa:2048 -nodes -keyout key.pem -x509 -days 365 -out certificate.pem
```

--------------------------------

### Quality Check Procedure

Source: https://github.com/demodorigatsuo/sharepoint-mcp/blob/main/docs/development-guidelines.md

Run all three quality checks – formatting with 'black', linting with 'ruff', and testing with 'pytest' – before each commit and pull request. All checks must pass without errors or failures.

```bash
# 1. Format
black .

# 2. Lint
ruff check .

# 3. Test
pytest
```

--------------------------------

### SharePoint MCP Server System Overview Diagram

Source: https://github.com/demodorigatsuo/sharepoint-mcp/blob/main/docs/functional-design.md

Mermaid diagram illustrating the interaction between the LLM Client, SharePoint MCP Server, Microsoft Entra ID, and SharePoint Online.

```mermaid
graph TD
    LLM[LLM Client
Claude Desktop / API] -->|MCP Protocol| MCP[SharePoint MCP Server
server.py]
    MCP -->|OAuth2 Client Credentials| AAD[Microsoft Entra ID
Azure AD]
    AAD -->|Access Token| MCP
    MCP -->|Microsoft Graph API| SP[SharePoint Online]

    subgraph MCP Server
        MCP --> Tools[tools/]
        MCP --> Resources[resources/]
        Tools --> Auth[auth/]
        Tools --> Utils[utils/]
        Resources --> Auth
    end
```

--------------------------------

### Run Tests

Source: https://github.com/demodorigatsuo/sharepoint-mcp/blob/main/CONTRIBUTING.md

Executes the project's test suite using pytest. Ensure all tests pass before submitting changes.

```bash
# Run tests
pytest
```

--------------------------------

### Quality Checks for Code Formatting, Linting, and Testing

Source: https://github.com/demodorigatsuo/sharepoint-mcp/blob/main/Claude.md

Commands to run automated quality checks on the codebase, including code formatting with black, linting with ruff, and running tests with pytest.

```bash
# Code formatting
black .

```

```bash
# Linting
ruff check .

```

```bash
# Tests
pytest

```

--------------------------------

### Diagnose Authentication Failures

Source: https://github.com/demodorigatsuo/sharepoint-mcp/blob/main/README.md

Run this script to diagnose authentication issues. It helps identify problems with your Azure AD app or permissions.

```bash
python auth-diagnostic.py
```

--------------------------------

### Lint Python Code with Ruff

Source: https://github.com/demodorigatsuo/sharepoint-mcp/blob/main/docs/development-guidelines.md

Employ the 'ruff' linter to maintain code quality and catch potential errors. Ensure all Python code passes 'ruff check' with zero errors.

```bash
ruff check .
```

--------------------------------

### SharePoint MCP Server Directory Tree

Source: https://github.com/demodorigatsuo/sharepoint-mcp/blob/main/docs/repository-structure.md

This is the overall directory structure for the SharePoint MCP Server project, showing the location of key files and subdirectories.

```tree
sharepoint-mcp/
├── server.py                    # MCP server entry point
├── setup.py                     # Package installation config
├── requirements.txt             # Runtime + dev dependencies
├── pytest.ini                   # pytest configuration
├── .env.example                 # Environment variable template
├── .gitignore
│
├── auth/                        # Authentication modules
│   ├── __init__.py
│   └── sharepoint_auth.py       # SharePointContext, get_auth_context, refresh_token_if_needed
│
├── config/                      # Configuration
│   ├── __init__.py
│   ├── settings.py              # Loads .env, exposes SHAREPOINT_CONFIG, APP_NAME, DEBUG
│   └── credentials.py.template  # Template for manual credential setup
│
├── tools/                       # MCP tool definitions
│   ├── __init__.py
│   └── site_tools.py            # register_site_tools() — all @mcp.tool() definitions
│
├── resources/                   # MCP resource definitions
│   ├── __init__.py
│   └── site.py                  # register_site_resources() — sharepoint://site-info
│
├── utils/                       # Shared utilities
│   ├── __init__.py
│   ├── graph_client.py          # GraphClient — HTTP wrapper for Microsoft Graph API
│   ├── document_processor.py    # DocumentProcessor — parses DOCX, PDF, XLSX, CSV, TXT
│   └── content_generator.py     # ContentGenerator — generates page titles and content
│
├── tests/                       # pytest test suite
│   ├── tests-init.py            # Test package init (non-standard name, see note)
│   ├── test_auth.py             # Tests for auth/sharepoint_auth.py
│   └── test_graph_client.py     # Tests for utils/graph_client.py
│
├── docs/                        # Persistent project documents
│   ├── product-requirements.md  # Product vision, user stories, acceptance criteria
│   ├── functional-design.md     # Per-feature architecture, data models, diagrams
│   ├── architecture.md          # Tech stack, constraints, deployment
│   ├── repository-structure.md  # This file
│   ├── development-guidelines.md # Coding conventions, testing standards, Git rules
│   ├── glossary.md              # Domain and code terminology
│   ├── auth_guide.md            # Azure AD setup and Graph API permissions
│   └── usage.md                 # Usage examples for LLM clients
│
├── .steering/                   # Task-scoped documents (one dir per task)
│   └── YYYYMMDD-task-title/
│       ├── requirements.md
│       ├── design.md
│       └── tasklist.md
│
├── .github/                     # GitHub configuration
│   ├── workflows/               # CI/CD (GitHub Actions)
│   ├── ISSUE_TEMPLATE/          # Bug report / feature request templates
│   └── PULL_REQUEST_TEMPLATE.md
│
└── auth-diagnostic.py           # Standalone auth diagnostic script
    config_checker.py            # Standalone config validation script
    token-decoder.py             # Standalone JWT token decoder script

```

--------------------------------

### Inspect Token Claims

Source: https://github.com/demodorigatsuo/sharepoint-mcp/blob/main/README.md

Use this script to decode and inspect the claims within your authentication tokens. This is useful for troubleshooting token-related issues.

```bash
python token-decoder.py
```

--------------------------------

### Format Python Code with Black

Source: https://github.com/demodorigatsuo/sharepoint-mcp/blob/main/docs/development-guidelines.md

Use the 'black' formatter to ensure consistent Python code style. It enforces a default line length of 88 characters and handles all formatting decisions automatically.

```bash
black .
```

--------------------------------

### SharePoint MCP Authentication Flow Diagram

Source: https://github.com/demodorigatsuo/sharepoint-mcp/blob/main/docs/functional-design.md

Mermaid sequence diagram detailing the OAuth2 client credentials flow for authenticating the MCP Server with Microsoft Entra ID and accessing Microsoft Graph API.

```mermaid
sequenceDiagram
    participant Server as MCP Server
    participant AAD as Microsoft Entra ID
    participant Graph as Microsoft Graph API

    Server->>AAD: POST /token (client_id, client_secret, scope)
    AAD-->>Server: access_token + expires_in
    Server->>Graph: GET /sites/{domain}:/sites/{name}
    Note over Server: Token auto-refreshed before expiry
    Graph-->>Server: Site data (JSON)
```

--------------------------------

### Tool Function Template

Source: https://github.com/demodorigatsuo/sharepoint-mcp/blob/main/docs/development-guidelines.md

Template for defining a new tool function within the MCP. Includes context handling, authentication checks, token refresh, and Graph API client usage. Ensure proper error handling and logging.

```python
@mcp.tool()
async def my_new_tool(ctx: Context, param: str) -> str:
    """One-line description shown to the LLM.

    Args:
        param: Description of the parameter
    """
    logger.info(f"Tool called: my_new_tool with param: {param}")
    try:
        sp_ctx = ctx.request_context.lifespan_context
        _check_auth(sp_ctx)
        await refresh_token_if_needed(sp_ctx)
        graph_client = GraphClient(sp_ctx)
        result = await graph_client.some_method(param)
        return json.dumps(result, indent=2)
    except Exception as e:
        logger.error(f"Error in my_new_tool: {str(e)}")
        raise
```

--------------------------------

### SharePoint MCP Error Handling Scenarios

Source: https://github.com/demodorigatsuo/sharepoint-mcp/blob/main/docs/functional-design.md

Details various error scenarios that can occur within the SharePoint MCP and their corresponding behaviors.

```markdown
| Scenario |
| Behavior |
|----------|----------|
| Auth failure at startup | Error context created; all tools raise descriptive exception |
| Invalid / expired token | `_check_auth()` raises before Graph API call |
| Graph API non-2xx | `GraphClient` raises `Exception("Graph API error: {status} - {body}")` |
| Document parse failure | `DocumentProcessor` returns `{"error": "..."}` dict |
| Tool exception | FastMCP marks tool call as error and surfaces message to LLM |
```

--------------------------------

### SharePointContext Fields Table

Source: https://github.com/demodorigatsuo/sharepoint-mcp/blob/main/docs/functional-design.md

Provides a detailed description of each field within the SharePointContext, including its type and purpose.

```markdown
| Field |
| Type |
| Description |
|-------|------|-------------|
| `access_token` | `str` | Bearer token for Microsoft Graph API |
| `token_expiry` | `datetime \| None` | UTC datetime when token expires |
| `graph_url` | `str` | Base URL (default: `https://graph.microsoft.com/v1.0`) |
```

--------------------------------

### Mermaid Graph Diagram

Source: https://github.com/demodorigatsuo/sharepoint-mcp/blob/main/Claude.md

Embeds a graph diagram directly within Markdown files using Mermaid syntax. This format is version-controlled and requires no external tooling.

```mermaid
graph TD
    A[User] --> B[Create Task]
    B --> C[Task List]
    C --> D[Edit Task]
    C --> E[Delete Task]
```

--------------------------------

### Git Commit Message Format for Other Changes

Source: https://github.com/demodorigatsuo/sharepoint-mcp/blob/main/docs/development-guidelines.md

Use specific prefixes like 'feat:', 'chore:', or 'docs:' for commit messages related to new features, maintenance tasks, or documentation updates, respectively. This categorizes changes effectively.

```git
feat: add create_news_post tool
chore: update requirements.txt versions
docs: add glossary.md
```

--------------------------------

### SharePointContext Entity Relationship Diagram

Source: https://github.com/demodorigatsuo/sharepoint-mcp/blob/main/docs/functional-design.md

Defines the structure of the SharePointContext object, including fields for access token, token expiry, and the Microsoft Graph API URL.

```mermaid
erDiagram
    SharePointContext {
        string access_token
        datetime token_expiry
        string graph_url
    }
```

--------------------------------

### Auto-fix Safe Ruff Issues

Source: https://github.com/demodorigatsuo/sharepoint-mcp/blob/main/docs/development-guidelines.md

Use 'ruff check --fix' to automatically correct safe linting issues, improving code consistency and reducing manual effort.

```bash
ruff check --fix .
```

--------------------------------

### Git Branch Naming Convention for Fixes

Source: https://github.com/demodorigatsuo/sharepoint-mcp/blob/main/docs/development-guidelines.md

Use the 'fix/issue-{number}-{summary}' format for branches that address specific issues. This convention helps in tracking bug fixes and their corresponding issue numbers.

```git
fix/issue-12-token-refresh-failure
fix/issue-34-search-returns-empty
```

--------------------------------

### Git Branch Naming Convention for Features

Source: https://github.com/demodorigatsuo/sharepoint-mcp/blob/main/docs/development-guidelines.md

For new features that are not tied to a specific issue number, use the 'feat/{summary}' format for branch naming. This clearly indicates the purpose of the branch.

```git
feat/{summary}
```

--------------------------------

### Git Commit Message Format for Fixes

Source: https://github.com/demodorigatsuo/sharepoint-mcp/blob/main/docs/development-guidelines.md

Commit messages for fixes should follow the 'fix: #[issue-number] - brief description of the change' format. This links commits directly to issue tracking.

```git
fix: #12 - refresh token before expiry on every tool call
fix: #34 - handle empty search results from Graph API
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.