MCP Protocol Integration (L1 Component)
Model Context Protocol (MCP) integration layer providing standardized access to Noosphere search capabilities. Enables seamless client integration through JSON-RPC 2.0 transport with comprehensive tool definitions and robust error handling.
Architecture Overview
text
┌──────────────────────────────────────────────┐
│ MCP Interface Layer │
│ ┌────────────────────────────────────────┐ │
│ │ JSON-RPC 2.0 │ │
│ │ Transport Protocol │ │
│ └────────────────┬───────────────────────┘ │
│ │ │
│ ┌────────────────▼───────────────────────┐ │
│ │ Tool Registry │ │
│ │ • Search Tools │ │
│ │ • AI Agent Tools │ │
│ │ • Graph Traversal Tools │ │
│ │ • Metadata Tools │ │
│ └────────────────┬───────────────────────┘ │
└───────────────────┼──────────────────────────┘
│
┌───────────────┼───────────────┐
│ │ │
▼ ▼ ▼
┌─────────┐ ┌─────────────┐ ┌─────────────┐
│Meta │ │ AI Staff │ │ Knowledge │
│Agent │ │ Collective │ │ Graph │
│Router │ │ │ │ Engine │
│ │ │• Librarian │ │ │
│• Cache │ │• Researcher │ │• Neo4j │
│• Route │ │• Validator │ │• Cypher │
│• Learn │ │• Navigator │ │• Analytics │
└─────────┘ └─────────────┘ └─────────────┘MCP Tool Definitions
Core Search Tools
1. Smart Search Router
json
{
"name": "noosphere_search",
"description": "Intelligent search routing across vector, graph, and AI agent capabilities",
"inputSchema": {
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "Natural language search query"
},
"context": {
"type": "object",
"properties": {
"user_id": {"type": "string"},
"session_id": {"type": "string"},
"search_history": {
"type": "array",
"items": {"type": "string"}
},
"domain_focus": {
"type": "string",
"enum": ["technical", "academic", "research", "implementation", "general"]
},
"depth": {
"type": "string",
"enum": ["surface", "moderate", "deep", "exhaustive"],
"default": "moderate"
},
"max_results": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 20
}
},
"required": ["user_id"]
},
"preferences": {
"type": "object",
"properties": {
"response_format": {
"type": "string",
"enum": ["structured", "narrative", "bullet_points", "detailed"],
"default": "structured"
},
"include_explanations": {
"type": "boolean",
"default": true
},
"quality_threshold": {
"type": "number",
"minimum": 0.0,
"maximum": 1.0,
"default": 0.7
},
"search_methods": {
"type": "array",
"items": {
"type": "string",
"enum": ["vector", "graph", "ai_agent", "hybrid"]
},
"default": ["hybrid"]
}
}
}
},
"required": ["query", "context"]
}
}2. Vector Search Tool
json
{
"name": "noosphere_vector_search",
"description": "Direct semantic vector search with embedding-based similarity",
"inputSchema": {
"type": "object",
"properties": {
"query": {"type": "string"},
"embedding_model": {
"type": "string",
"enum": ["text-embedding-ada-002", "all-mpnet-base-v2", "domain-specific"],
"default": "text-embedding-ada-002"
},
"similarity_threshold": {
"type": "number",
"minimum": 0.0,
"maximum": 1.0,
"default": 0.75
},
"result_count": {
"type": "integer",
"minimum": 1,
"maximum": 50,
"default": 10
},
"include_metadata": {
"type": "boolean",
"default": true
}
},
"required": ["query"]
}
}3. Graph Traversal Tool
json
{
"name": "noosphere_graph_traversal",
"description": "Knowledge graph exploration and relationship discovery",
"inputSchema": {
"type": "object",
"properties": {
"start_concepts": {
"type": "array",
"items": {"type": "string"},
"description": "Starting concept names or IDs"
},
"relationship_types": {
"type": "array",
"items": {
"type": "string",
"enum": ["RELATED_TO", "IS_SUBCONCEPT_OF", "EVOLVES_INTO", "REQUIRES", "CITES"]
},
"default": ["RELATED_TO"]
},
"max_depth": {
"type": "integer",
"minimum": 1,
"maximum": 5,
"default": 3
},
"min_relationship_strength": {
"type": "number",
"minimum": 0.0,
"maximum": 1.0,
"default": 0.3
},
"include_path_explanations": {
"type": "boolean",
"default": true
}
},
"required": ["start_concepts"]
}
}AI Agent Integration Tools
4. AI Librarian Tool
json
{
"name": "ai_librarian",
"description": "Specialized librarian agent for information discovery and cataloging",
"inputSchema": {
"type": "object",
"properties": {
"task_type": {
"type": "string",
"enum": ["discover", "catalog", "bibliography", "quality_assess"]
},
"query": {"type": "string"},
"domain": {
"type": "string",
"enum": ["computer_science", "machine_learning", "software_engineering", "research", "general"]
},
"output_format": {
"type": "string",
"enum": ["source_list", "categorized_catalog", "bibliography", "quality_report"],
"default": "source_list"
},
"citation_style": {
"type": "string",
"enum": ["apa", "ieee", "chicago", "mla"],
"default": "apa"
}
},
"required": ["task_type", "query"]
}
}5. AI Researcher Tool
json
{
"name": "ai_researcher",
"description": "Deep analysis, synthesis, and knowledge connection specialist",
"inputSchema": {
"type": "object",
"properties": {
"research_type": {
"type": "string",
"enum": ["analyze_patterns", "synthesize_insights", "identify_gaps", "generate_hypotheses"]
},
"input_documents": {
"type": "array",
"items": {"type": "string"},
"description": "Document IDs or content for analysis"
},
"focus_area": {
"type": "string",
"enum": ["technical", "academic", "market", "historical"]
},
"analysis_depth": {
"type": "string",
"enum": ["overview", "detailed", "comprehensive"],
"default": "detailed"
},
"output_format": {
"type": "string",
"enum": ["summary", "structured_report", "insights_list", "hypothesis_set"],
"default": "structured_report"
}
},
"required": ["research_type", "input_documents"]
}
}6. AI Validator Tool
json
{
"name": "ai_validator",
"description": "Quality assurance, fact-checking, and credibility assessment",
"inputSchema": {
"type": "object",
"properties": {
"validation_type": {
"type": "string",
"enum": ["verify_facts", "assess_bias", "check_consistency", "validate_methodology"]
},
"content": {
"type": "string",
"description": "Content to validate (text, document ID, or claim)"
},
"validation_depth": {
"type": "string",
"enum": ["shallow", "standard", "deep", "expert_level"],
"default": "standard"
},
"cross_reference": {
"type": "boolean",
"default": true,
"description": "Whether to cross-reference with external sources"
},
"output_format": {
"type": "string",
"enum": ["summary", "detailed_report", "score_only", "structured_assessment"],
"default": "structured_assessment"
}
},
"required": ["validation_type", "content"]
}
}7. AI Navigator Tool
json
{
"name": "ai_navigator",
"description": "Investigation guidance and complex reasoning pathway management",
"inputSchema": {
"type": "object",
"properties": {
"navigation_type": {
"type": "string",
"enum": ["plan_investigation", "suggest_next_steps", "resolve_ambiguity", "orchestrate_agents"]
},
"objective": {
"type": "string",
"description": "Research objective or goal to achieve"
},
"current_state": {
"type": "object",
"properties": {
"completed_steps": {"type": "array", "items": {"type": "string"}},
"findings": {"type": "array", "items": {"type": "string"}},
"remaining_questions": {"type": "array", "items": {"type": "string"}},
"constraints": {"type": "array", "items": {"type": "string"}}
}
},
"strategy_preference": {
"type": "string",
"enum": ["breadth_first", "depth_first", "hybrid", "iterative_refinement"],
"default": "hybrid"
}
},
"required": ["navigation_type", "objective"]
}
}Metadata and Analytics Tools
8. Search Metadata Tool
json
{
"name": "search_metadata",
"description": "Retrieve search history, analytics, and performance metadata",
"inputSchema": {
"type": "object",
"properties": {
"metadata_type": {
"type": "string",
"enum": ["search_history", "performance_stats", "user_preferences", "system_health"]
},
"search_id": {
"type": "string",
"description": "Specific search ID for detailed metadata"
},
"user_id": {
"type": "string",
"description": "User ID for personalized metadata"
},
"time_range": {
"type": "object",
"properties": {
"start": {"type": "string", "format": "date-time"},
"end": {"type": "string", "format": "date-time"}
}
}
},
"required": ["metadata_type"]
}
}Response Schemas
Standard Response Format
json
{
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": ["success", "partial_success", "error"]
},
"request_id": {"type": "string"},
"timestamp": {"type": "string", "format": "date-time"},
"results": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {"type": "string"},
"title": {"type": "string"},
"content": {"type": "string"},
"type": {
"type": "string",
"enum": ["document", "concept", "author", "repository", "insight"]
},
"relevance_score": {
"type": "number",
"minimum": 0.0,
"maximum": 1.0
},
"source": {
"type": "object",
"properties": {
"url": {"type": "string"},
"publication_date": {"type": "string", "format": "date"},
"authors": {"type": "array", "items": {"type": "string"}},
"venue": {"type": "string"}
}
},
"metadata": {"type": "object"}
},
"required": ["id", "title", "relevance_score"]
}
},
"metadata": {
"type": "object",
"properties": {
"total_results": {"type": "integer"},
"search_method": {
"type": "string",
"enum": ["vector", "graph", "ai_agent", "hybrid"]
},
"processing_time_ms": {"type": "integer"},
"confidence": {
"type": "number",
"minimum": 0.0,
"maximum": 1.0
},
"explanation": {"type": "string"},
"suggestions": {
"type": "array",
"items": {"type": "string"}
}
}
},
"errors": {
"type": "array",
"items": {
"type": "object",
"properties": {
"code": {"type": "string"},
"message": {"type": "string"},
"details": {"type": "object"}
}
}
}
},
"required": ["status", "request_id", "timestamp", "results", "metadata"]
}Authentication and Security
API Key Authentication
json
{
"authentication": {
"type": "api_key",
"header": "X-Noosphere-API-Key",
"validation": {
"algorithm": "HMAC-SHA256",
"expiration": "24h",
"rate_limiting": {
"requests_per_minute": 100,
"requests_per_hour": 1000,
"burst_limit": 20
}
}
}
}User Context Management
python
class UserContextManager:
def create_session(self, user_id: str, client_info: ClientInfo) -> Session:
"""Create new user session with context tracking"""
session = Session(
id=self.generate_session_id(),
user_id=user_id,
client_info=client_info,
created_at=datetime.utcnow(),
search_history=[],
preferences=self.load_user_preferences(user_id),
context_window=ContextWindow(max_size=10)
)
self.active_sessions[session.id] = session
return session
def update_context(self, session_id: str, search_result: SearchResult):
"""Update user context with search results"""
session = self.active_sessions[session_id]
# Add to search history
session.search_history.append(SearchHistoryEntry(
query=search_result.query,
timestamp=datetime.utcnow(),
results_count=len(search_result.results),
method_used=search_result.metadata.search_method
))
# Update context window for personalization
session.context_window.add_entry(ContextEntry(
type="search",
content=search_result.query,
results=search_result.results[:3], # Top 3 results
timestamp=datetime.utcnow()
))
# Update user preferences based on interaction patterns
self.update_preferences(session.user_id, search_result)Error Handling and Resilience
Error Codes and Messages
json
{
"error_codes": {
"INVALID_QUERY": {
"code": "ERR_1001",
"message": "Query format is invalid or empty",
"http_status": 400
},
"AUTHENTICATION_FAILED": {
"code": "ERR_2001",
"message": "Invalid or expired API key",
"http_status": 401
},
"RATE_LIMIT_EXCEEDED": {
"code": "ERR_2002",
"message": "Rate limit exceeded for this API key",
"http_status": 429
},
"SEARCH_TIMEOUT": {
"code": "ERR_3001",
"message": "Search operation timed out",
"http_status": 504
},
"AGENT_UNAVAILABLE": {
"code": "ERR_3002",
"message": "Requested AI agent is temporarily unavailable",
"http_status": 503
},
"GRAPH_DATABASE_ERROR": {
"code": "ERR_4001",
"message": "Graph database connection failed",
"http_status": 500
},
"VECTOR_SEARCH_ERROR": {
"code": "ERR_4002",
"message": "Vector search engine error",
"http_status": 500
}
}
}Circuit Breaker Pattern
python
class NoosphereCircuitBreaker:
def __init__(self, failure_threshold: int = 5, timeout: int = 60):
self.failure_threshold = failure_threshold
self.timeout = timeout
self.failure_count = 0
self.last_failure_time = None
self.state = "CLOSED" # CLOSED, OPEN, HALF_OPEN
def call_with_circuit_breaker(self, func, *args, **kwargs):
"""Execute function with circuit breaker protection"""
if self.state == "OPEN":
if self._should_attempt_reset():
self.state = "HALF_OPEN"
else:
raise CircuitBreakerOpenError("Service temporarily unavailable")
try:
result = func(*args, **kwargs)
self._on_success()
return result
except Exception as e:
self._on_failure()
raise e
def _on_success(self):
"""Reset circuit breaker on successful operation"""
self.failure_count = 0
self.state = "CLOSED"
def _on_failure(self):
"""Handle failure and potentially open circuit"""
self.failure_count += 1
self.last_failure_time = time.time()
if self.failure_count >= self.failure_threshold:
self.state = "OPEN"
def _should_attempt_reset(self) -> bool:
"""Check if enough time has passed to attempt reset"""
return (time.time() - self.last_failure_time) >= self.timeoutClient Integration Examples
Python Client
python
import asyncio
from mcp import Client, ClientSession
from mcp.client.stdio import stdio_client
class NoosphereClient:
def __init__(self, api_key: str):
self.api_key = api_key
self.session = None
async def connect(self):
"""Establish MCP connection to Noosphere server"""
self.session = await stdio_client(
server_params={"api_key": self.api_key},
server_command=["noosphere-mcp-server"]
)
async def search(self,
query: str,
context: dict = None,
preferences: dict = None) -> dict:
"""Perform intelligent search"""
result = await self.session.call_tool(
"noosphere_search",
arguments={
"query": query,
"context": context or {"user_id": "default"},
"preferences": preferences or {}
}
)
return result
async def ask_librarian(self,
query: str,
task_type: str = "discover") -> dict:
"""Interact with AI librarian agent"""
result = await self.session.call_tool(
"ai_librarian",
arguments={
"task_type": task_type,
"query": query,
"domain": "general"
}
)
return result
# Usage example
async def main():
client = NoosphereClient("your-api-key")
await client.connect()
# Perform search
search_results = await client.search(
"transformer architecture attention mechanisms",
context={"domain_focus": "technical", "depth": "deep"},
preferences={"response_format": "detailed", "max_results": 15}
)
# Ask librarian to catalog findings
catalog_results = await client.ask_librarian(
"catalog transformer architecture papers from search results",
task_type="catalog"
)
print(f"Found {len(search_results['results'])} results")
print(f"Cataloged {len(catalog_results['results'])} sources")
if __name__ == "__main__":
asyncio.run(main())TypeScript/JavaScript Client
typescript
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
interface SearchContext {
user_id: string;
domain_focus?: 'technical' | 'academic' | 'research' | 'implementation' | 'general';
depth?: 'surface' | 'moderate' | 'deep' | 'exhaustive';
max_results?: number;
}
interface SearchPreferences {
response_format?: 'structured' | 'narrative' | 'bullet_points' | 'detailed';
include_explanations?: boolean;
quality_threshold?: number;
}
class NoosphereClient {
private client: Client;
private transport: StdioClientTransport;
constructor(private apiKey: string) {}
async connect(): Promise<void> {
this.transport = new StdioClientTransport({
command: 'noosphere-mcp-server',
args: ['--api-key', this.apiKey]
});
this.client = new Client(
{ name: 'noosphere-client', version: '1.0.0' },
{ capabilities: {} }
);
await this.client.connect(this.transport);
}
async search(
query: string,
context: SearchContext,
preferences?: SearchPreferences
): Promise<any> {
const result = await this.client.request(
{
method: 'tools/call',
params: {
name: 'noosphere_search',
arguments: {
query,
context,
preferences: preferences || {}
}
}
},
{}
);
return result;
}
async traverseGraph(
startConcepts: string[],
options: {
maxDepth?: number;
relationshipTypes?: string[];
minStrength?: number;
} = {}
): Promise<any> {
const result = await this.client.request(
{
method: 'tools/call',
params: {
name: 'noosphere_graph_traversal',
arguments: {
start_concepts: startConcepts,
max_depth: options.maxDepth || 3,
relationship_types: options.relationshipTypes || ['RELATED_TO'],
min_relationship_strength: options.minStrength || 0.3
}
}
},
{}
);
return result;
}
}
// Usage example
async function example() {
const client = new NoosphereClient('your-api-key');
await client.connect();
try {
const searchResults = await client.search(
'machine learning interpretability',
{
user_id: 'user-123',
domain_focus: 'technical',
depth: 'deep',
max_results: 25
},
{
response_format: 'structured',
include_explanations: true,
quality_threshold: 0.8
}
);
console.log('Search Results:', searchResults);
// Follow up with graph traversal
const graphResults = await client.traverseGraph(
['machine learning', 'interpretability'],
{
maxDepth: 2,
relationshipTypes: ['RELATED_TO', 'IS_SUBCONCEPT_OF'],
minStrength: 0.5
}
);
console.log('Graph Traversal:', graphResults);
} catch (error) {
console.error('Error:', error);
}
}Performance Monitoring and Analytics
Request Tracking
python
class MCPRequestTracker:
def __init__(self):
self.metrics = {
'total_requests': 0,
'requests_by_tool': defaultdict(int),
'response_times': [],
'error_rates': defaultdict(int),
'user_patterns': defaultdict(list)
}
def track_request(self,
tool_name: str,
user_id: str,
response_time: float,
success: bool):
"""Track MCP request metrics"""
self.metrics['total_requests'] += 1
self.metrics['requests_by_tool'][tool_name] += 1
self.metrics['response_times'].append(response_time)
if not success:
self.metrics['error_rates'][tool_name] += 1
self.metrics['user_patterns'][user_id].append({
'tool': tool_name,
'timestamp': datetime.utcnow(),
'response_time': response_time,
'success': success
})
def generate_analytics_report(self) -> dict:
"""Generate comprehensive analytics report"""
avg_response_time = np.mean(self.metrics['response_times'])
p95_response_time = np.percentile(self.metrics['response_times'], 95)
error_rates = {
tool: (errors / self.metrics['requests_by_tool'][tool]) * 100
for tool, errors in self.metrics['error_rates'].items()
}
return {
'summary': {
'total_requests': self.metrics['total_requests'],
'avg_response_time_ms': avg_response_time,
'p95_response_time_ms': p95_response_time,
'overall_error_rate': sum(self.metrics['error_rates'].values()) / self.metrics['total_requests'] * 100
},
'tool_usage': dict(self.metrics['requests_by_tool']),
'error_rates': error_rates,
'active_users': len(self.metrics['user_patterns'])
}Related Links
Explore related documentation:
- Noosphere Layer - README — overview and quick navigation.
- AI Staff — librarian/researcher roles and flows.
- Architecture — internal design and data flows.
- Hyperbolic Space — spatial memory concepts.
- Knowledge Graph — schemas and traversal patterns.