# Bing Search MCP Server

A Model Context Protocol (MCP) server that provides AI-grounded Bing search capabilities using Azure AI Project Client. This server enables intelligent web searches with citation tracking and URL extraction.

## Features

- **AI-Grounded Search**: Leverages Azure AI agents for intelligent search results
- **Citation Tracking**: Automatically extracts and formats citations with URLs
- **MCP Protocol**: Compatible with MCP clients for seamless integration
- **HTTP Transport**: Runs as HTTP server on port 8000 for remote access

## Prerequisites

- Python 3.8 or higher
- Azure subscription with AI Project configured
- Azure AD App Registration (for service principal authentication)
- Bing Search resource enabled in your Azure AI Project

## Installation

### Using pip

```bash
pip install -r requirements.txt
```

### Using Docker

```bash
docker build -t bing-search-mcp .
docker run --env-file .env bing-search-mcp
```

## Configuration

Create a `.env` file in the project root with the following variables:

```env
PROJECT_ENDPOINT=https://your-project.cognitiveservices.azure.com/
AGENT_ID=your-agent-id
TENANT_ID=your-azure-tenant-id
CLIENT_ID=your-azure-client-id
CLIENT_SECRET=your-azure-client-secret
```

See `.env.example` for a template.

## Usage

### Running the Server

#### HTTP Mode (default)

The server runs on `http://0.0.0.0:8000` by default:

```bash
python bing-search.py
```

The server will be accessible at:

- Local: `http://localhost:8000`
- Network: `http://<your-ip>:8000`

#### Stdio Mode

To use stdio transport, modify `bing-search.py`:

```python
# TRANSPORT = "streamable-http"
TRANSPORT = "stdio"
```

And update the run call:

```python
bing_mcp.run(transport=TRANSPORT)
```

### Available Tools

#### `bing_grounded_with_ai`

Performs an AI-grounded Bing search with citation tracking.

**Parameters:**

- `query` (str): The search query

**Returns:**

- Response text with inline citations in Markdown format
- List of extracted URLs with titles

**Example:**

```python
result_text, urls = bing_grounded_with_ai("What is the latest news about AI?")
print(result_text)  # Text with [Title](URL) citations
print(urls)         # [["Title1", "url1"], ["Title2", "url2"], ...]
```

## Architecture

The server uses:

- **FastMCP**: Simplified MCP server implementation
- **Azure AI Project Client**: Manages AI agents and threads
- **Azure Identity**: Handles service principal authentication

## Error Handling

The server includes comprehensive error handling for:

- Missing or invalid queries
- Azure credential issues
- Agent execution failures
- Thread cleanup errors

All errors are returned as `ToolError` exceptions with descriptive messages.

## Development

### Project Structure

```
bing-search/
├── bing-search.py      # Main MCP server implementation
├── requirements.txt    # Python dependencies
├── Dockerfile         # Container configuration
├── .env              # Environment variables (not in git)
├── .env.example      # Environment template
└── README.md         # This file
```

### Transport Modes

- **streamable-http**: HTTP server for remote access (default, port 8000)
- **stdio**: Communicates via standard input/output (alternative mode)

## Docker Support

The included Dockerfile creates a lightweight container optimized for production use:

- Based on Python 3.11-slim for minimal image size
- Non-root user for enhanced security
- Multi-stage build process
- Optimized layer caching

### Build and Run

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

# Run with environment file
docker run -p 8000:8000 --env-file .env bing-search-mcp

# Run with individual environment variables
docker run -p 8000:8000 \
  -e PROJECT_ENDPOINT="your-endpoint" \
  -e AGENT_ID="your-agent-id" \
  -e TENANT_ID="your-tenant-id" \
  -e CLIENT_ID="your-client-id" \
  -e CLIENT_SECRET="your-client-secret" \
  bing-search-mcp

# Access the server
curl http://localhost:8000
```

## Security Considerations

- Never commit `.env` file or credentials to version control
- Use Azure Key Vault for production secrets management
- Rotate service principal credentials regularly
- Apply principle of least privilege to Azure AD app permissions

## Troubleshooting

### Common Issues

**Authentication Errors:**

- Verify all Azure credentials are correct
- Ensure service principal has appropriate permissions
- Check if credentials have expired

**Agent Not Found:**

- Confirm AGENT_ID exists in your Azure AI Project
- Verify PROJECT_ENDPOINT is correct

**Connection Issues:**

- Check network connectivity to Azure
- Verify firewall rules allow outbound HTTPS

## License

MIT

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## Support

For issues and questions:

- Create an issue in the repository
- Check Azure AI Project documentation
- Review MCP protocol specifications