API.md•14.9 kB
# API Documentation - MCP Wikipedia Server
Complete API reference for the MCP Wikipedia Server tools and client integration.
## 🔗 Server Endpoint
**Base URL**: `stdio://` (MCP uses stdin/stdout communication)
**Protocol**: Model Context Protocol (MCP) v1.0
**Transport**: Standard I/O streams
## 🛠️ Available Tools
### 1. fetch_wikipedia_info
Searches Wikipedia and returns article summary with metadata.
#### Parameters
| Parameter | Type | Required | Description | Default |
|-----------|------|----------|-------------|---------|
| `query` | `string` | ✅ | Search query or article title | - |
#### Request Example
```json
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "fetch_wikipedia_info",
"arguments": {
"query": "Artificial Intelligence"
}
}
}
```
#### Response Format
```json
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"content": [
{
"type": "text",
"text": "{\n \"success\": true,\n \"data\": {\n \"title\": \"Artificial intelligence\",\n \"summary\": \"Artificial intelligence (AI) is intelligence demonstrated by machines...\",\n \"url\": \"https://en.wikipedia.org/wiki/Artificial_intelligence\",\n \"page_id\": 1266637,\n \"length\": 15234,\n \"links\": [\"Machine learning\", \"Deep learning\", \"Neural network\"],\n \"categories\": [\"Artificial intelligence\", \"Computer science\"],\n \"last_modified\": \"2024-01-15T10:30:00Z\"\n },\n \"metadata\": {\n \"query\": \"Artificial Intelligence\",\n \"search_time_ms\": 245,\n \"timestamp\": \"2024-01-15T10:30:15.123Z\"\n }\n}"
}
]
}
}
```
#### Success Response Fields
| Field | Type | Description |
|-------|------|-------------|
| `success` | `boolean` | Always `true` for successful requests |
| `data.title` | `string` | Official Wikipedia article title |
| `data.summary` | `string` | Article summary (first paragraph) |
| `data.url` | `string` | Direct link to Wikipedia article |
| `data.page_id` | `integer` | Unique Wikipedia page identifier |
| `data.length` | `integer` | Total article length in characters |
| `data.links` | `array[string]` | Related article links |
| `data.categories` | `array[string]` | Article categories |
| `data.last_modified` | `string` | Last modification timestamp (ISO 8601) |
| `metadata.query` | `string` | Original search query |
| `metadata.search_time_ms` | `integer` | Search execution time in milliseconds |
| `metadata.timestamp` | `string` | Request timestamp (ISO 8601) |
#### Error Response
```json
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"content": [
{
"type": "text",
"text": "{\n \"success\": false,\n \"error\": \"Article not found\",\n \"error_type\": \"NotFoundError\",\n \"suggestions\": [\"Artificial intelligence\", \"AI research\"],\n \"metadata\": {\n \"query\": \"Artifical Inteligence\",\n \"timestamp\": \"2024-01-15T10:30:15.123Z\"\n }\n}"
}
]
}
}
```
---
### 2. list_wikipedia_sections
Retrieves all section titles from a Wikipedia article.
#### Parameters
| Parameter | Type | Required | Description | Default |
|-----------|------|----------|-------------|---------|
| `topic` | `string` | ✅ | Article title or search query | - |
#### Request Example
```json
{
"jsonrpc": "2.0",
"id": 2,
"method": "tools/call",
"params": {
"name": "list_wikipedia_sections",
"arguments": {
"topic": "Machine Learning"
}
}
}
```
#### Response Format
```json
{
"jsonrpc": "2.0",
"id": 2,
"result": {
"content": [
{
"type": "text",
"text": "{\n \"success\": true,\n \"data\": {\n \"article_title\": \"Machine learning\",\n \"sections\": [\n {\n \"title\": \"Overview\",\n \"level\": 2,\n \"index\": 1\n },\n {\n \"title\": \"Definition\",\n \"level\": 2,\n \"index\": 2\n },\n {\n \"title\": \"History\",\n \"level\": 2,\n \"index\": 3\n },\n {\n \"title\": \"Early developments\",\n \"level\": 3,\n \"index\": 4\n },\n {\n \"title\": \"Types\",\n \"level\": 2,\n \"index\": 5\n }\n ],\n \"total_sections\": 15\n },\n \"metadata\": {\n \"topic\": \"Machine Learning\",\n \"page_id\": 233488,\n \"timestamp\": \"2024-01-15T10:30:15.123Z\"\n }\n}"
}
]
}
}
```
#### Success Response Fields
| Field | Type | Description |
|-------|------|-------------|
| `success` | `boolean` | Always `true` for successful requests |
| `data.article_title` | `string` | Resolved Wikipedia article title |
| `data.sections` | `array[object]` | List of article sections |
| `data.sections[].title` | `string` | Section title |
| `data.sections[].level` | `integer` | Heading level (2-6) |
| `data.sections[].index` | `integer` | Section order index |
| `data.total_sections` | `integer` | Total number of sections |
| `metadata.topic` | `string` | Original topic query |
| `metadata.page_id` | `integer` | Wikipedia page identifier |
| `metadata.timestamp` | `string` | Request timestamp (ISO 8601) |
---
### 3. get_section_content
Retrieves the content of a specific section from a Wikipedia article.
#### Parameters
| Parameter | Type | Required | Description | Default |
|-----------|------|----------|-------------|---------|
| `topic` | `string` | ✅ | Article title or search query | - |
| `section_title` | `string` | ✅ | Exact section title to retrieve | - |
#### Request Example
```json
{
"jsonrpc": "2.0",
"id": 3,
"method": "tools/call",
"params": {
"name": "get_section_content",
"arguments": {
"topic": "Python (programming language)",
"section_title": "History"
}
}
}
```
#### Response Format
```json
{
"jsonrpc": "2.0",
"id": 3,
"result": {
"content": [
{
"type": "text",
"text": "{\n \"success\": true,\n \"data\": {\n \"article_title\": \"Python (programming language)\",\n \"section_title\": \"History\",\n \"content\": \"Python was conceived in the late 1980s by Guido van Rossum...\",\n \"content_length\": 1247,\n \"subsections\": [\n \"Origins\",\n \"Version history\",\n \"Python 2 vs Python 3\"\n ],\n \"section_level\": 2\n },\n \"metadata\": {\n \"topic\": \"Python (programming language)\",\n \"section_title\": \"History\",\n \"page_id\": 23862,\n \"timestamp\": \"2024-01-15T10:30:15.123Z\"\n }\n}"
}
]
}
}
```
#### Success Response Fields
| Field | Type | Description |
|-------|------|-------------|
| `success` | `boolean` | Always `true` for successful requests |
| `data.article_title` | `string` | Resolved Wikipedia article title |
| `data.section_title` | `string` | Retrieved section title |
| `data.content` | `string` | Section content (plain text) |
| `data.content_length` | `integer` | Content length in characters |
| `data.subsections` | `array[string]` | Subsection titles (if any) |
| `data.section_level` | `integer` | Section heading level |
| `metadata.topic` | `string` | Original topic query |
| `metadata.section_title` | `string` | Original section title query |
| `metadata.page_id` | `integer` | Wikipedia page identifier |
| `metadata.timestamp` | `string` | Request timestamp (ISO 8601) |
## ❌ Error Handling
### Common Error Types
| Error Type | HTTP Code | Description | Retry Recommended |
|------------|-----------|-------------|-------------------|
| `NotFoundError` | 404 | Article or section not found | No |
| `DisambiguationError` | 300 | Multiple articles match query | No (use suggestions) |
| `NetworkError` | 503 | Wikipedia API unavailable | Yes (with backoff) |
| `RateLimitError` | 429 | Too many requests | Yes (with delay) |
| `ValidationError` | 400 | Invalid parameters | No |
| `TimeoutError` | 408 | Request timeout | Yes |
### Error Response Format
```json
{
"success": false,
"error": "Human readable error message",
"error_type": "NotFoundError",
"error_code": "ARTICLE_NOT_FOUND",
"suggestions": ["Alternative 1", "Alternative 2"],
"metadata": {
"query": "original query",
"timestamp": "2024-01-15T10:30:15.123Z"
}
}
```
### Error Response Fields
| Field | Type | Description |
|-------|------|-------------|
| `success` | `boolean` | Always `false` for errors |
| `error` | `string` | Human-readable error message |
| `error_type` | `string` | Error classification |
| `error_code` | `string` | Machine-readable error code |
| `suggestions` | `array[string]` | Alternative queries (when available) |
| `metadata` | `object` | Request context information |
## 🔌 Client Integration
### Python Client Example
```python
import asyncio
import json
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client
async def call_wikipedia_tool():
server_params = StdioServerParameters(
command="python",
args=["src/mcp_server/mcp_server.py"]
)
async with stdio_client(server_params) as (read, write):
async with ClientSession(read, write) as session:
# Initialize the session
await session.initialize()
# List available tools
tools = await session.list_tools()
print("Available tools:", [tool.name for tool in tools.tools])
# Call a tool
result = await session.call_tool(
"fetch_wikipedia_info",
{"query": "Artificial Intelligence"}
)
# Parse result
data = json.loads(result.content[0].text)
print("Article title:", data["data"]["title"])
print("Summary:", data["data"]["summary"][:200] + "...")
# Run the client
asyncio.run(call_wikipedia_tool())
```
### JavaScript/Node.js Client Example
```javascript
const { spawn } = require('child_process');
const { Client } = require('@modelcontextprotocol/sdk/client/index.js');
const { StdioClientTransport } = require('@modelcontextprotocol/sdk/client/stdio.js');
async function callWikipediaTool() {
// Start the server process
const serverProcess = spawn('python', ['src/mcp_server/mcp_server.py']);
// Create MCP client
const transport = new StdioClientTransport({
stdin: serverProcess.stdin,
stdout: serverProcess.stdout
});
const client = new Client({
name: "wikipedia-client",
version: "1.0.0"
}, {
capabilities: {}
});
await client.connect(transport);
try {
// List available tools
const tools = await client.listTools();
console.log('Available tools:', tools.tools.map(t => t.name));
// Call the tool
const result = await client.callTool({
name: "fetch_wikipedia_info",
arguments: {
query: "Machine Learning"
}
});
const data = JSON.parse(result.content[0].text);
console.log('Article:', data.data.title);
console.log('Summary:', data.data.summary.substring(0, 200) + '...');
} finally {
await client.close();
serverProcess.kill();
}
}
callWikipediaTool().catch(console.error);
```
## 📊 Rate Limits and Performance
### Rate Limits
| Resource | Limit | Window | Notes |
|----------|-------|--------|-------|
| Wikipedia API | 100 req/min | Per IP | Built-in handling |
| MCP Server | 1000 req/min | Per client | Configurable |
| Concurrent requests | 10 | Simultaneous | Per client session |
### Performance Characteristics
| Operation | Avg Response Time | Max Response Time | Cache TTL |
|-----------|-------------------|-------------------|-----------|
| Article search | 200-500ms | 2s | 5 minutes |
| Section listing | 300-600ms | 2.5s | 10 minutes |
| Section content | 400-800ms | 3s | 15 minutes |
### Optimization Tips
1. **Batch Requests**: Group multiple queries when possible
2. **Caching**: Responses are cached automatically
3. **Connection Reuse**: Keep MCP session alive for multiple calls
4. **Error Handling**: Implement exponential backoff for retries
5. **Specific Queries**: Use exact article titles when known
## 🔒 Security Considerations
### Input Validation
- All queries are sanitized before Wikipedia API calls
- Maximum query length: 1000 characters
- Special characters are properly escaped
- No code execution in search queries
### Output Sanitization
- HTML tags removed from Wikipedia content
- URLs validated before inclusion
- Content length limits enforced
- No sensitive information exposure
### Network Security
- HTTPS only for Wikipedia API calls
- No external data storage
- Session-based operation only
- No persistent connections to external services
## 📈 Monitoring and Metrics
### Available Metrics
```json
{
"server_stats": {
"uptime_seconds": 3600,
"total_requests": 1247,
"successful_requests": 1203,
"failed_requests": 44,
"average_response_time_ms": 450,
"cache_hit_rate": 0.73
},
"tool_stats": {
"fetch_wikipedia_info": {
"calls": 892,
"success_rate": 0.96,
"avg_response_time_ms": 420
},
"list_wikipedia_sections": {
"calls": 234,
"success_rate": 0.98,
"avg_response_time_ms": 380
},
"get_section_content": {
"calls": 121,
"success_rate": 0.94,
"avg_response_time_ms": 520
}
}
}
```
## 🔧 Configuration Options
### Environment Variables
| Variable | Default | Description |
|----------|---------|-------------|
| `WIKIPEDIA_LANGUAGE` | `en` | Wikipedia language code |
| `WIKIPEDIA_USER_AGENT` | `MCP-Wikipedia-Server/1.0` | User agent for API calls |
| `CACHE_TTL_SECONDS` | `300` | Cache time-to-live |
| `MAX_SEARCH_RESULTS` | `10` | Maximum search results |
| `REQUEST_TIMEOUT_SECONDS` | `30` | API request timeout |
| `LOG_LEVEL` | `INFO` | Logging level |
### Server Configuration
```python
# Custom configuration example
server_config = {
"wikipedia": {
"language": "en",
"user_agent": "Custom-MCP-Client/1.0",
"timeout": 30,
"max_results": 10
},
"cache": {
"ttl": 300,
"max_size": 1000
},
"logging": {
"level": "INFO",
"format": "%(asctime)s - %(name)s - %(levelname)s - %(message)s"
}
}
```
---
## 📞 Support and Resources
- **GitHub Issues**: [Report bugs and request features](https://github.com/your-repo/issues)
- **MCP Specification**: [Official MCP documentation](https://spec.modelcontextprotocol.io/)
- **Wikipedia API**: [Python Wikipedia library docs](https://wikipedia.readthedocs.io/)
For additional support, please refer to the [GUIDE.md](GUIDE.md) and [DEVELOPMENT.md](DEVELOPMENT.md) files.