Metadata-Version: 2.4
Name: stackoverflow-fastmcp
Version: 1.3.3
Summary: StackOverflow MCP server for querying programming Q&A using FastMCP framework
Project-URL: Homepage, https://github.com/NoTalkTech/stackoverflow-mcp
Project-URL: Documentation, https://github.com/NoTalkTech/stackoverflow-mcp#readme
Project-URL: Repository, https://github.com/NoTalkTech/stackoverflow-mcp.git
Project-URL: Bug Tracker, https://github.com/NoTalkTech/stackoverflow-mcp/issues
Project-URL: Changelog, https://github.com/NoTalkTech/stackoverflow-mcp/blob/main/CHANGELOG.md
Author-email: "biyu.huang" <h417652303@gmail.com>
Maintainer-email: "biyu.huang" <h417652303@gmail.com>
License: MIT
License-File: LICENSE
Keywords: api,cli,mcp,model-context-protocol,programming,qa,search,server,stackoverflow
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
Classifier: Topic :: Software Development :: Documentation
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Text Processing :: Markup :: Markdown
Requires-Python: >=3.12
Requires-Dist: beautifulsoup4>=4.12.0
Requires-Dist: click>=8.0.0
Requires-Dist: fastmcp>=0.9.0
Requires-Dist: httpx>=0.25.0
Requires-Dist: markdownify>=0.11.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: python-dotenv>=1.0.0
Provides-Extra: dev
Requires-Dist: black>=23.0.0; extra == 'dev'
Requires-Dist: coverage>=7.0.0; extra == 'dev'
Requires-Dist: mypy>=1.0.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
Requires-Dist: pytest-httpx>=0.21.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Provides-Extra: test
Requires-Dist: coverage>=7.0.0; extra == 'test'
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'test'
Requires-Dist: pytest-httpx>=0.21.0; extra == 'test'
Requires-Dist: pytest>=7.0.0; extra == 'test'
Description-Content-Type: text/markdown

# StackOverflow MCP Server

[![npm version](https://badge.fury.io/js/@notalk-tech%2Fstackoverflow-mcp.svg)](https://badge.fury.io/js/@notalk-tech%2Fstackoverflow-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

A Model Context Protocol (MCP) server that provides seamless access to StackOverflow's programming Q&A database using the FastMCP framework.

## Quick Start

### Using with Cursor (Recommended)

Add this configuration to your Cursor MCP settings:

```json
{
  "mcp_servers": {
    "stackoverflow": {
      "command": "npx",
      "args": [
        "-y",
        "@notalk-tech/stackoverflow-mcp",
        "--api-key", "your_stackoverflow_api_key"
      ]
    }
  }
}
```

### Using NPX

```bash
# Run directly (no installation required)
npx @notalk-tech/stackoverflow-mcp

# With API key
npx @notalk-tech/stackoverflow-mcp --api-key your_key

# Skip installation prompts
npx -y @notalk-tech/stackoverflow-mcp
```

### Using Python Module

```bash
# Direct execution
python -m stackoverflow_mcp

# With uv (recommended)
uv run python -m stackoverflow_mcp --api-key your_key
```

## 🎯 Features

- **🔍 Advanced Search**: Search by keywords, tags, accepted status, score threshold, and date ranges
- **📖 Question Details**: Get detailed content with automatic HTML-to-Markdown conversion
- **🏷️ Tag-based Search**: Convenient tag-only search (proxies to main search)
- **💡 Related Questions**: Discover related and linked questions for deeper exploration
- **⚡ Rate Limit Management**: Intelligent retry, backoff, and auto-switching between authenticated/unauthenticated access
- **🔐 API Authentication**: Full support for StackOverflow API keys with automatic quota tracking
- **📦 Unified Response Format**: All tools return consistent `{success, data, meta}` structure
- **🚀 Auto-deployment**: NPX-compatible with automatic Python environment setup

## 🔑 Getting Your API Key

To use this MCP server with higher rate limits, you'll need a StackOverflow API key:

### Steps

1. **Register Your Application**
   - Visit https://stackapps.com/applications/register
   - Log in with your Stack Exchange account
   - Fill in application details (name, description, OAuth domain)
   - Submit the registration

2. **Generate Your API Key**
   - Go to your application management page
   - Click **"Generate a new API key"**
   - Copy and save the generated key securely

### Rate Limits

- **Without API key**: 300 requests/day per IP
- **With API key**: 10,000 requests/day

For read-only operations (searching and retrieving Q&A), a simple API key is sufficient. OAuth is only needed for write operations.

**Learn more**: https://api.stackexchange.com/docs/authentication

## ⚙️ Configuration

Create a `.stackoverflow-mcp.json` file in your working directory:

```json
{
  "stackoverflow_api_key": "your_api_key_here",
  "log_level": "CRITICAL"
}
```

The server auto-discovers config files in this order:
1. `.stackoverflow-mcp.json`
2. `stackoverflow-mcp.config.json`
3. `config/stackoverflow-mcp.json`
4. `.config/stackoverflow-mcp.json`

### Command Line Options

```
--working-dir DIRECTORY    Working directory (auto-detect if not specified)
--api-key TEXT             StackOverflow API key
--version                  Show version and exit
--help                     Show help message
```

## 🌐 Available Tools

Once running, the MCP server provides these tools:

- **`search_questions`**: Search StackOverflow questions by keywords with optional filters — `tags`, `accepted_only`, `min_score`, `from_date`, `to_date`
- **`search_by_tags`**: Convenience wrapper for tag-only search (proxies to `search_questions`)
- **`get_question`**: Get detailed question content with optional answer limiting (`max_answers`) and automatic HTML-to-Markdown conversion
- **`get_answers`**: Fetch answers independently without re-fetching the question body
- **`get_related`**: Discover related and linked questions for further exploration

### Resource

- **`stackoverflow://status`**: Server status including version, authentication state, rate limit status, and queue statistics

## 📋 Prerequisites

- **Node.js** 14.0.0 or higher
- **Python** 3.12 or higher
- **uv** (recommended) or **pip**

The NPX wrapper automatically handles Python package installation and environment setup.

## 🚀 Development

### Local Setup

```bash
git clone https://github.com/NoTalkTech/stackoverflow-mcp.git
cd stackoverflow-mcp

# Install dependencies
npm install
pip install -e .

# Run in development mode
npm start
```

### Project Structure

```
stackoverflow-mcp/
├── cli.js                          # NPX wrapper (Node.js)
├── package.json                    # NPM package configuration
├── pyproject.toml                  # Python package configuration
├── src/stackoverflow_mcp/          # Python MCP server
│   ├── __main__.py                 # Python module entry point
│   ├── main.py                     # CLI and server management
│   ├── server.py                   # MCP server implementation (5 tools + resource)
│   ├── config.py                   # Server configuration management
│   ├── logging.py                  # Logging configuration
│   └── stackoverflow_client.py     # StackOverflow API client (rate limiting, caching, content formatting)
└── tests/                          # Test files
```

### Testing

```bash
# Run all tests
.venv/bin/python -m pytest tests/ -v

# Test npm package
npm test
```

## 🤝 Contributing

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🆘 Support

- **Issues**: [GitHub Issues](https://github.com/NoTalkTech/stackoverflow-mcp/issues)
- **Documentation**: [GitHub README](https://github.com/NoTalkTech/stackoverflow-mcp#readme)

## 🙏 Acknowledgments

- [Model Context Protocol](https://github.com/modelcontextprotocol) for the MCP specification
- [StackOverflow](https://stackoverflow.com/) for providing the API
- The open-source community for inspiration and contributions

---

**Made for the developer community**
