SharePoint MCP Server

# Development Guide ## Project Status ✅ **Production-Ready** - All core functionality implemented and tested ## Architecture ### Core Components 1. **FastMCP Server** (`server.py`) - 10 tools for SharePoint operations - 1 resource for user info - 2 prompts for common tasks - Lifespan management for auth/client initialization 2. **OAuth Authentication** (`auth.py`) - Browser-based OAuth flow with PKCE - OS keychain token storage (macOS Keychain, Windows Credential Manager, Linux Secret Service) - Automatic token refresh - MSAL integration 3. **Graph API Client** (`graph.py`) - Async HTTP client with httpx - Automatic retry with exponential backoff - Rate limit handling - Token refresh on 401 4. **Pydantic Models** (`models/`) - Structured output for all tools - Type-safe data validation - Automatic JSON schema generation 5. **Configuration** (`config.py`) - Environment variable support - Config file support - Flexible configuration options ## Test Coverage ```bash # Run tests uv run pytest # Run with coverage uv run pytest --cov=sharepoint_mcp --cov-report=html # View coverage report open htmlcov/index.html ``` **Current Status**: 31 tests passing, ~85% coverage ## Code Quality ```bash # Type checking uv run mypy src/sharepoint_mcp --check-untyped-defs # Linting uv run ruff check src/sharepoint_mcp # Auto-fix linting issues uv run ruff check --fix src/sharepoint_mcp # Format code uv run ruff format src/sharepoint_mcp ``` **Current Status**: All checks passing ✅ ## Local Development ### Setup ```bash # Install dependencies uv sync --dev uv pip install -e ".[dev]" # Activate virtual environment (optional, uv runs commands in venv automatically) source .venv/bin/activate ``` ### Running the Server ```bash # Set environment variables export AZURE_CLIENT_ID="your-client-id" export AZURE_TENANT_ID="your-tenant-id" export LOG_LEVEL="DEBUG" # Run the server uv run sharepoint-mcp ``` ### Testing with Claude Desktop Add to `~/Library/Application Support/Claude/claude_desktop_config.json`: ```json { "mcpServers": { "sharepoint-dev": { "command": "uv", "args": ["--directory", "/Users/ezequielmrivero/eze/custom_mcps/sharepoint-mcp", "run", "sharepoint-mcp"], "env": { "AZURE_CLIENT_ID": "your-client-id", "AZURE_TENANT_ID": "your-tenant-id", "LOG_LEVEL": "DEBUG" } } } } ``` Restart Claude Desktop and check the logs: - macOS: `~/Library/Logs/Claude/mcp-server-sharepoint-dev.log` ## Available Tools | Tool | Implementation Status | Tests | |------|----------------------|-------| | `list_sites` | ✅ | ✅ | | `list_libraries` | ✅ | ✅ | | `list_files` | ✅ | ✅ | | `search_files` | ✅ | ✅ | | `get_file_content` | ✅ | ✅ | | `upload_file` | ✅ | ✅ | | `get_file_metadata` | ✅ | ✅ | | `create_sharing_link` | ✅ | ✅ | | `list_items` | ✅ | ✅ | | `create_list_item` | ✅ | ✅ | ## Publishing to PyPI ### Prerequisites 1. Create account on [PyPI](https://pypi.org) 2. Configure API token 3. Update version in `pyproject.toml` ### Build and Publish ```bash # Build the package uv build # Publish to PyPI (will prompt for credentials) uv publish # Or publish to TestPyPI first uv publish --index-url https://test.pypi.org/legacy/ ``` ### Testing the Published Package ```bash # Install from PyPI uvx sharepoint-mcp # Or from TestPyPI uvx --index-url https://test.pypi.org/simple/ sharepoint-mcp ``` ## Future Enhancements ### Potential Features 1. **Large File Upload** - Implement resumable upload for files > 4MB - Use Graph API large file upload session 2. **Additional Tools** - `delete_file` - Delete files - `move_file` - Move/rename files - `update_list_item` - Update existing list items - `list_lists` - Discover SharePoint lists - `get_permissions` - Check file/site permissions 3. **Performance Optimizations** - Implement caching for site/library metadata - Batch requests where possible - Connection pooling 4. **Enhanced Search** - Support for advanced KQL queries - Filter by file type, date, author - Faceted search results 5. **Webhooks/Notifications** - Subscribe to file changes - Real-time updates via Server-Sent Events ### Code Improvements 1. **Better Error Handling** - Custom exception hierarchy - More granular error messages - Retry policies for specific error types 2. **Logging Enhancements** - Structured logging (JSON) - Request/response tracing - Performance metrics 3. **Configuration** - Support for multiple tenants/apps - Per-site configuration - Custom timeout/retry settings ## Troubleshooting Development Issues ### Import Errors **Problem**: `ModuleNotFoundError: No module named 'sharepoint_mcp'` **Solution**: ```bash uv pip install -e . ``` ### Tests Failing **Problem**: Authentication tests fail **Solution**: Tests use mocks and don't require real credentials. Check that `respx` is installed: ```bash uv pip install -e ".[dev]" ``` ### Type Checking Issues **Problem**: mypy reports errors about missing stubs **Solution**: Add type ignore comments for third-party libraries without stubs: ```python import msal # type: ignore[import-untyped] ``` ## Contributing ### Code Style - Follow PEP 8 - Use type hints throughout - Write docstrings (Google style) - Keep functions focused and testable - Prefer explicit over implicit ### Git Workflow ```bash # Create feature branch git checkout -b feature/my-feature # Make changes and commit git add . git commit -m "Add: description of changes" # Run tests and checks uv run pytest uv run mypy src/sharepoint_mcp uv run ruff check src/sharepoint_mcp # Push and create PR git push origin feature/my-feature ``` ### Commit Message Format - `Add:` - New feature - `Fix:` - Bug fix - `Update:` - Modification to existing feature - `Refactor:` - Code restructuring - `Docs:` - Documentation changes - `Test:` - Test additions/modifications ## Resources - [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk) - [FastMCP Documentation](https://github.com/modelcontextprotocol/python-sdk/tree/main/src/mcp/server/fastmcp) - [Microsoft Graph API Reference](https://docs.microsoft.com/en-us/graph/api/overview) - [MSAL Python Documentation](https://msal-python.readthedocs.io/) - [Pydantic Documentation](https://docs.pydantic.dev/)