Universal Context Gateway (UCG)

An extensible server adhering to the Model Context Protocol (MCP) specification, designed to harmonize retrieval of decentralized social graph metadata and associated on-chain records. Primary support is established for Farcaster operations leveraging the Neynar API service, with a clear pathway reserved for incorporating Twitter data streams. Future enhancements will encompass additional data sources, such as Telegram data, alongside comprehensive on-chain query capabilities.

Core Capabilities

• MCP Conformance: Fully adheres to all mandates outlined in the Model Context Protocol specification.
• Multi-Source Support: Architected for seamless interoperability across diverse social media ecosystems.
• Adaptable Architecture: Simplifies the incorporation of novel data provider modules.
• LLM Serialization: Contextual payloads are meticulously structured for optimal interpretation by generative models.
• Versatile Transmission: Supports both traditional direct I/O (stdio) and modern streaming/web-based transport mechanisms (SSE/HTTP).

Active Data Sources

• Farcaster: Complete implementation facilitated through the Neynar API interface.
• X (Twitter): Currently designated as a development placeholder (unimplemented).

Initial Setup Guide

Prerequisites

• Runtime Environment: Node.js version 16 or newer.
• Authorization: A valid API credential for Neynar is mandatory for Farcaster data access. Obtain one at https://neynar.com/

Deployment

1. Obtain the source code repository:

git clone https://github.com/yourusername/beyond-mcp-server.git
cd beyond-mcp-server

1. Install necessary runtime dependencies:

npm install

1. Initialize configuration file structure:

cp .env.example .env
# Modify the newly created .env file with your secrets

1. Configure Environment Variables
2. Mandatory Setting: Populate the NEYNAR_API_KEY entry within your .env file.
3. Credential acquisition link: https://neynar.com/

4. Operation failure will occur for Farcaster features without a provisioned, valid API key.

5. Initiate the service:

npm run build
npm start  # Executes in default stdio mode
# OR for web-based streaming:
npm run start:http  

Integrating with Claude Desktop

1. Compile the project artifacts:

npm run build

1. Verify environment configuration:
2. Ensure the .env file is correctly positioned, as the system searches:
   • The current execution directory.
   • The project's top-level directory.
   • Up to three ancestral directories.

3. Alternatively, environment variables can be set directly at the operating system level.

4. Update Claude Desktop Configuration File Location:

5. MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json
6. Windows: %APPDATA%\Claude\claude_desktop_config.json

Configuration Snippet (stdio mode):

{
  "mcpServers": {
    "universal-data-gateway": {
      "command": "/usr/local/bin/node",
      "args": [
        "/full/path/to/beyond-mcp-server/dist/index.js",
        "--stdio"
      ]
    }
  }
}

1. Recommended: Injecting Secrets Directly into Configuration:

{
  "mcpServers": {
    "universal-data-gateway": {
      "command": "/usr/local/bin/node",
      "args": [
        "/full/path/to/beyond-mcp-server/dist/index.js",
        "--stdio"
      ],
      "env": {
        "NEYNAR_API_KEY": "YOUR_API_KEY_HERE",
        "ENABLE_FARCASTER": "true",
        "ENABLE_TWITTER": "false"
      }
    }
  }
}

1. Relaunch the Claude Desktop application to apply changes.

MCP Endpoint Definitions

Resource Schemas

• social://{platform}/{query}/search - Execute platform-specific content lookups.
• social://{platform}/user/{userId}/profile - Retrieve a specified user's descriptive metadata.
• social://{platform}/wallet/{walletAddress}/profile - Obtain user identity details linked to a cryptocurrency address (Farcaster context only).
• social://{platform}/user/{userId}/balance - Query the associated cryptocurrency holdings of a user (Farcaster context only).
• Input acceptance: Accepts either the numerical FID or the associated username handle.
• Resolution Logic: If a username is supplied, automatic conversion to the canonical FID precedes the data fetch.
• social://{platform}/wallet/{walletAddress}/profile - Fetch profile attributes mapped to a specific ledger address.
• social://{platform}/user/{userId}/content - Retrieve the published artifacts by a given user identifier.
• social://{platform}/thread/{threadId} - Fetch the complete sequence of messages within a discussion chain.
• social://{platform}/trending - Query for currently popular subjects or topics.
• social://{platform}/trending-feed - Access curated, multi-sourced trending content streams (Farcaster context only).
• Supported Providers: neynar (default selection), openrank, mbd.
• Configurables: timeWindow (options: 1h, 6h, 12h, 24h, 7d, 30d), limit.
• social://{platform}/channels/search - Discover channels based on criteria (Farcaster context only).
• Parameters: query string, limit constraint, cursor for pagination.
• Output: Delivers channel metadata including name, summary, subscriber volume, and structural attributes.
• social://{platform}/channels/bulk-search - Facilitate parallelized discovery of multiple channels (Farcaster context only).
• Parameters: queries (an array of search terms), limit, cursor.
• Output: Provides segmented results for each input query, complete with channel specifics and pagination indices.

Operational Tools

• search-content - Mechanism for querying platform content reservoirs.
• get-user-profile - Toolset for extracting detailed user profile attributes.
• get-user-profile-by-wallet - Retrieves user identity data mapped via a wallet identifier (Farcaster scope).
• get-user-balance - Tool to ascertain user asset holdings (Farcaster scope).
• Input flexibility: Accepts FID or username.
• Automatic resolution of username to FID is integrated.
• get-user-content - Utility for fetching an individual user's published outputs.
• get-thread - Tool for reconstructing conversation threads.
• get-trending-topics - Accessor for current prevailing subjects.
• getTrendingFeed - Utility for aggregating multi-source trending streams (Farcaster scope).
• get-wallet-profile - Retrieves identity linked to a blockchain address.
• search-channels - Tool for platform channel discovery (Farcaster scope).
• Parameters: query, result count cap, pagination token.
• Returns: Comprehensive channel statistics including follower counts and schema metadata.
• search-bulk-channels - Executes parallelized channel exploration (Farcaster scope).
• Parameters: queries (array structure), limit, cursor.
• Returns: Comparative results for all submitted search terms with associated pagination data.

Action Prompts

• analyze-thread - Facilitates in-depth analysis of a specific social media discussion segment.
• summarize-user-activity - Generates a consolidated report on a user's documented actions.
• explore-trending-topics - Tool for examining and interpreting prevalent subjects on a given network.
• analyze-search-results - Evaluates the corpus retrieved from a content search query.
• explore-trending-feed - Performs comparative analysis on content feeds aggregated from multiple providers.
• get-wallet-profile - Fetches and subsequently analyzes profile attributes linked to a cryptographic wallet.
• check-user-balance - Assesses a user's current asset portfolio and holdings.
• Supports both direct FID and username inputs.
• Includes intrinsic capability for resolving usernames to FIDs.
• explore-channels - Deconstructs and analyzes discovered channels, providing metrics on engagement and content relevance.
• explore-bulk-channels - Executes concurrent analysis across multiple channels to map relationships and emerging patterns.

Architectural Extension: Integrating New Data Sources

To incorporate support for an additional social data provider:

1. Establish a new subdirectory within the src/providers/ structure.
2. Implement all required methods dictated by the ContentProvider interface within a new class.
3. Register this newly created provider within the central service registry mechanism.

Illustrative Code Structure:

import { ContentProvider } from '../interfaces/provider';

export class MyPlatformProvider implements ContentProvider {
  public name = 'myplatform';
  public platform = 'myplatform';

  // Fulfill all mandated interface methods here
}

Development Lifecycle

Running in Iterative Mode

npm run dev        # Activates stdio debugging channel
npm run dev:http   # Activates HTTP/SSE debugging channel

Automated Testing Suite

npm test

Code Quality Enforcement

npm run lint
npm run lint:fix

Licensing

Distributed under the terms of the MIT License.

Community Involvement

We actively encourage external contributions! Please feel invited to submit a Pull Request for review.

Revision History

All substantive alterations to this codebase are cataloged within this file.

### [1.0.0] - 2025-Mar-10

#### Additions - Launch stabilization. - Integration of Farcaster functionality via the Neynar SDK. - Establishment of the core MCP compliant server engine. - Support activation for both direct I/O and HTTP transmission protocols.

### [1.0.1] - 2025-Mar-19

#### Additions - Introduction of new retrieval tools for obtaining user profiles based on associated wallet addresses. - Augmentation of the existing test suite.

### [1.0.2] - 2025-Mar-21

#### Additions - Implementation enabling the retrieval of Farcaster user holdings (balances) using either their numerical ID or handle. - Enablement of multi-source aggregation for the trending feed endpoint. - Enhancement of the UpdateUserProfile procedure to include supplementary user attributes. - Deployment of extensive validation tests to guarantee operational robustness and throughput.

### [1.0.3] - 2025-Mar-24

#### Additions - Integration of capabilities for querying Farcaster channel details, supporting both single and bulk requests.