Content
# Python Project Analyzer MCP Server
[](https://www.python.org/)
[](https://modelcontextprotocol.io)
[](https://fastapi.tiangolo.com/)
[](https://opensource.org/licenses/MIT)
[]()
A Model Context Protocol (MCP) server that provides tools for analyzing Python projects, extracting library signatures, and retrieving project information.
## Overview
This MCP server provides tools to help AI assistants analyze Python projects, extract information about libraries, and understand project dependencies. It's designed to be used with MCP-compatible clients like Claude.
## Features
- **Project Dependencies Analysis**: Extract dependencies from `pyproject.toml` files
- **File Information Retrieval**: Get detailed information about files in a project
- **Library Signature Extraction**: Extract function and class signatures from Python libraries with search capabilities
## Requirements
- Python 3.11+
- Dependencies:
- `mcp>=0.9.1`
- `pydantic>=2.0.0`
- `fastapi>=0.90.0`
- `uvicorn[standard]`
- `httpx>=0.27.0`
- `toml>=0.10.2`
- `requests>=2.32.3`
## Installation
1. Clone the repository:
```bash
git clone https://github.com/yourusername/python-project-analyzer-mcp.git
cd python-project-analyzer-mcp
```
2. Install dependencies with uv:
```bash
uv sync
```
3. Install additional dependencies if needed:
```bash
# Install a development dependency
uv add pytest --dev
# Install a regular dependency
uv add requests
# Install dependencies from a specific group
uv add ruff --group lint
# Sync all dependencies including development ones
uv sync
# Sync only development dependencies
uv sync --only-dev
# Sync with specific groups
uv sync --group lint
# Sync all groups
uv sync --all-groups
```
## Usage
### Running the Server
You can run the server directly:
```bash
python mcp_server_sdk.py
```
### Connecting to Claude or Other MCP Clients
To use this server with Claude Desktop:
1. Install the MCP server:
```bash
mcp install /path/to/mcp_server_sdk.py --name "Python Project Analyzer"
```
2. The server will appear in Claude's available tools list.
### Available Tools
#### 1. Get Project Dependencies
Extracts dependencies from a project's `pyproject.toml` file.
```json
{
"jsonrpc": "2.0",
"method": "get_project_dependencies",
"params": {
"project_path": "/path/to/project"
},
"id": "request-id"
}
```
#### 2. Get File Information
Returns detailed information about a specified file.
```json
{
"jsonrpc": "2.0",
"method": "get_file_info",
"params": {
"file_path": "/path/to/file.py"
},
"id": "request-id"
}
```
#### 3. Extract Library Signatures
Searches for and extracts function or class signatures from a specified library.
```json
{
"jsonrpc": "2.0",
"method": "extract_library_signatures",
"params": {
"library_name": "json",
"project_path": "/path/to/project",
"search_term": "dump",
"max_results": 5,
"exact_match": false
},
"id": "request-id"
}
```
## Testing
Run the tests to verify the server is working correctly:
```bash
pytest test_mcp_client.py
```
## Project Structure
- `mcp_server_sdk.py`: Main MCP server implementation
- `helper_script.py`: Helper functions for library inspection
- `test_mcp_client.py`: Client tests for the MCP server
- `test_mcp_server.py`: Server unit tests
- `pyproject.toml`: Project dependencies and metadata
## Understanding MCP
The [Model Context Protocol (MCP)](https://modelcontextprotocol.io) is a standardized way for AI models to interact with external tools and resources. Key concepts include:
- **Tools**: Functions that models can call to perform actions or retrieve information
- **Resources**: External data sources that models can reference
- **Transports**: Communication channels between clients and MCP servers
This server implements the MCP specification to provide Python project analysis tools to AI assistants.
## Learning Resources
- [MCP Official Documentation](https://modelcontextprotocol.io/docs)
- [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk)
- [Claude Desktop](https://claude.ai/download)
## Installation on Windsurf
To install and use this MCP server in the Windsurf environment, follow these steps:
1. Clone the repository into your MCP servers directory:
```bash
git clone https://github.com/yourusername/python-project-analyzer-mcp.git ~/mcp-servers/mcp-python
cd ~/mcp-servers/mcp-python
```
2. Install dependencies using uv:
```bash
uv sync
```
3. Configure Windsurf to use this MCP server by updating your MCP configuration file:
```bash
mkdir -p ~/.codeium/windsurf
```
4. Create or update the MCP configuration file:
```bash
cat > ~/.codeium/windsurf/mcp_config.json << EOF
{
"mcp_servers": [
{
"name": "python-analyzer",
"command": ["python", "$HOME/mcp-servers/mcp-python/mcp_server_sdk.py"]
}
]
}
EOF
```
5. Restart Windsurf to apply the changes.
6. Verify the installation by checking if the MCP server appears in the available tools list in Windsurf.
For more detailed information, refer to the Windsurf documentation at @web https://docs.windsurf.com
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
```
MIT License
Copyright (c) 2025 [Your Name]
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.
```
