pulselink-mcp 0.3.0__tar.gz

pulselink_mcp-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Audel Rouhi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pulselink_mcp-0.3.0/MANIFEST.in

@@ -0,0 +1,4 @@
+include LICENSE
+include README.md
+include requirements.txt
+recursive-include pulselink_mcp *.py *.json

pulselink_mcp-0.3.0/PKG-INFO

@@ -0,0 +1,134 @@
+Metadata-Version: 2.4
+Name: pulselink-mcp
+Version: 0.3.0
+Summary: PulseLink — keyless open-web & social research source (MCP Server + A2A Server)
+Author-email: Audel Rouhi <knucklessg1@gmail.com>
+License: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Environment :: Console
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Requires-Python: <3.15,>=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: agent-utilities>=0.51.0
+Requires-Dist: python-dotenv>=1.0.0
+Provides-Extra: mcp
+Requires-Dist: agent-utilities[mcp]>=0.51.0; extra == "mcp"
+Provides-Extra: agent
+Requires-Dist: agent-utilities[agent,logfire]>=0.51.0; extra == "agent"
+Provides-Extra: youtube
+Requires-Dist: yt-dlp>=2024.0; extra == "youtube"
+Provides-Extra: feeds
+Requires-Dist: feedparser>=6.0; extra == "feeds"
+Provides-Extra: audio
+Requires-Dist: faster-whisper>=1.0; extra == "audio"
+Provides-Extra: sources
+Requires-Dist: pulselink-mcp[feeds,youtube]>=0.3.0; extra == "sources"
+Provides-Extra: all
+Requires-Dist: pulselink-mcp[agent,audio,feeds,logfire,mcp,youtube]>=0.3.0; extra == "all"
+Provides-Extra: test
+Requires-Dist: pytest-xdist>=3.6.0; extra == "test"
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: pytest-asyncio; extra == "test"
+Requires-Dist: pytest-cov; extra == "test"
+Requires-Dist: feedparser>=6.0; extra == "test"
+Dynamic: license-file
+
+# PulseLink MCP
+## CLI or API | MCP | Agent
+
+![PyPI - Version](https://img.shields.io/pypi/v/pulselink-mcp)
+![MCP Server](https://badge.mcpx.dev?type=server 'MCP Server')
+![PyPI - Downloads](https://img.shields.io/pypi/dd/pulselink-mcp)
+![GitHub Repo stars](https://img.shields.io/github/stars/Knuckles-Team/pulselink-mcp)
+![PyPI - License](https://img.shields.io/pypi/l/pulselink-mcp)
+![GitHub last commit (by committer)](https://img.shields.io/github/last-commit/Knuckles-Team/pulselink-mcp)
+
+*Version: 0.3.0*
+
+> **Documentation** — Installation, deployment, usage across the API, CLI, and MCP
+> interfaces, the integrated A2A agent server, and guidance for provisioning the
+> backing platform are maintained in the
+> [official documentation](https://knuckles-team.github.io/pulselink-mcp/).
+
+---
+
+## Overview
+
+**PulseLink MCP MCP Server + A2A Agent**
+
+PulseLink — keyless open-web & social research source (MCP Server + A2A Server)
+
+This repository is actively maintained - Contributions are welcome!
+
+## MCP
+
+### Using as an MCP Server
+
+The MCP Server can be run in `stdio` (local), `streamable-http` (networked), or
+`sse` mode.
+
+#### Environment Variables
+
+*   `PULSELINK_MCP_URL`: The URL of the target service.
+*   `PULSELINK_MCP_TOKEN`: The API token or access token.
+
+#### stdio Transport (local IDEs — Cursor, Claude Desktop, VS Code)
+
+```json
+{
+  "mcpServers": {
+    "pulselink-mcp": {
+      "command": "uvx",
+      "args": ["--from", "pulselink-mcp", "pulselink-mcp"],
+      "env": {
+        "PULSELINK_MCP_URL": "https://service.example.com",
+        "PULSELINK_MCP_TOKEN": "your_token"
+      }
+    }
+  }
+}
+```
+
+#### Streamable-HTTP Transport (networked / production)
+
+```json
+{
+  "mcpServers": {
+    "pulselink-mcp": {
+      "command": "uvx",
+      "args": ["--from", "pulselink-mcp", "pulselink-mcp", "--transport", "streamable-http", "--port", "8000"],
+      "env": {
+        "TRANSPORT": "streamable-http",
+        "HOST": "0.0.0.0",
+        "PORT": "8000",
+        "PULSELINK_MCP_URL": "https://service.example.com",
+        "PULSELINK_MCP_TOKEN": "your_token"
+      }
+    }
+  }
+}
+```
+
+<!-- BEGIN GENERATED: additional-deployment-options -->
+### Additional Deployment Options
+
+`pulselink-mcp` can also run as a **local container** (Docker / Podman / `uv`) or be
+consumed from a **remote deployment**. The
+[Deployment guide](https://knuckles-team.github.io/pulselink-mcp/deployment/) has full,
+copy-paste `mcp_config.json` for all four transports — **stdio**, **streamable-http**,
+**local container / uv**, and **remote URL**:
+
+- **Local container / uv** — launch the server from `mcp_config.json` via `uvx`,
+  `docker run`, or `podman run`, or point at a local streamable-http container by `url`.
+- **Remote URL** — connect to a server deployed behind Caddy at
+  `http://pulselink-mcp.arpa/mcp` using the `"url"` key.
+<!-- END GENERATED: additional-deployment-options -->
+
+## Install Python Package
+
+```bash
+python -m pip install pulselink-mcp
+```

pulselink_mcp-0.3.0/README.md

@@ -0,0 +1,96 @@
+# PulseLink MCP
+## CLI or API | MCP | Agent
+
+![PyPI - Version](https://img.shields.io/pypi/v/pulselink-mcp)
+![MCP Server](https://badge.mcpx.dev?type=server 'MCP Server')
+![PyPI - Downloads](https://img.shields.io/pypi/dd/pulselink-mcp)
+![GitHub Repo stars](https://img.shields.io/github/stars/Knuckles-Team/pulselink-mcp)
+![PyPI - License](https://img.shields.io/pypi/l/pulselink-mcp)
+![GitHub last commit (by committer)](https://img.shields.io/github/last-commit/Knuckles-Team/pulselink-mcp)
+
+*Version: 0.3.0*
+
+> **Documentation** — Installation, deployment, usage across the API, CLI, and MCP
+> interfaces, the integrated A2A agent server, and guidance for provisioning the
+> backing platform are maintained in the
+> [official documentation](https://knuckles-team.github.io/pulselink-mcp/).
+
+---
+
+## Overview
+
+**PulseLink MCP MCP Server + A2A Agent**
+
+PulseLink — keyless open-web & social research source (MCP Server + A2A Server)
+
+This repository is actively maintained - Contributions are welcome!
+
+## MCP
+
+### Using as an MCP Server
+
+The MCP Server can be run in `stdio` (local), `streamable-http` (networked), or
+`sse` mode.
+
+#### Environment Variables
+
+*   `PULSELINK_MCP_URL`: The URL of the target service.
+*   `PULSELINK_MCP_TOKEN`: The API token or access token.
+
+#### stdio Transport (local IDEs — Cursor, Claude Desktop, VS Code)
+
+```json
+{
+  "mcpServers": {
+    "pulselink-mcp": {
+      "command": "uvx",
+      "args": ["--from", "pulselink-mcp", "pulselink-mcp"],
+      "env": {
+        "PULSELINK_MCP_URL": "https://service.example.com",
+        "PULSELINK_MCP_TOKEN": "your_token"
+      }
+    }
+  }
+}
+```
+
+#### Streamable-HTTP Transport (networked / production)
+
+```json
+{
+  "mcpServers": {
+    "pulselink-mcp": {
+      "command": "uvx",
+      "args": ["--from", "pulselink-mcp", "pulselink-mcp", "--transport", "streamable-http", "--port", "8000"],
+      "env": {
+        "TRANSPORT": "streamable-http",
+        "HOST": "0.0.0.0",
+        "PORT": "8000",
+        "PULSELINK_MCP_URL": "https://service.example.com",
+        "PULSELINK_MCP_TOKEN": "your_token"
+      }
+    }
+  }
+}
+```
+
+<!-- BEGIN GENERATED: additional-deployment-options -->
+### Additional Deployment Options
+
+`pulselink-mcp` can also run as a **local container** (Docker / Podman / `uv`) or be
+consumed from a **remote deployment**. The
+[Deployment guide](https://knuckles-team.github.io/pulselink-mcp/deployment/) has full,
+copy-paste `mcp_config.json` for all four transports — **stdio**, **streamable-http**,
+**local container / uv**, and **remote URL**:
+
+- **Local container / uv** — launch the server from `mcp_config.json` via `uvx`,
+  `docker run`, or `podman run`, or point at a local streamable-http container by `url`.
+- **Remote URL** — connect to a server deployed behind Caddy at
+  `http://pulselink-mcp.arpa/mcp` using the `"url"` key.
+<!-- END GENERATED: additional-deployment-options -->
+
+## Install Python Package
+
+```bash
+python -m pip install pulselink-mcp
+```

pulselink_mcp-0.3.0/pulselink_mcp/__init__.py

@@ -0,0 +1,54 @@
+#!/usr/bin/env python
+
+import importlib
+import inspect
+import warnings
+
+warnings.filterwarnings("ignore", message=".*urllib3.*or chardet.*")
+
+__all__: list[str] = []
+
+CORE_MODULES = [
+    "pulselink_mcp.api",
+]
+
+OPTIONAL_MODULES = {
+    "pulselink_mcp.agent_server": "agent",
+    "pulselink_mcp.mcp_server": "mcp",
+}
+
+
+def _import_module_safely(module_name: str):
+    """Try to import a module and return it, or None if not available."""
+    try:
+        return importlib.import_module(module_name)
+    except ImportError:
+        return None
+
+
+def _expose_members(module):
+    """Expose public classes and functions from a module into globals and __all__."""
+    for name, obj in inspect.getmembers(module):
+        if (inspect.isclass(obj) or inspect.isfunction(obj)) and not name.startswith(
+            "_"
+        ):
+            globals()[name] = obj
+            __all__.append(name)
+
+
+for module_name in CORE_MODULES:
+    try:
+        module = importlib.import_module(module_name)
+        _expose_members(module)
+    except ImportError:
+        pass
+
+for module_name, extra_name in OPTIONAL_MODULES.items():
+    module = _import_module_safely(module_name)
+    if module is not None:
+        _expose_members(module)
+        globals()[f"_{extra_name.upper()}_AVAILABLE"] = True
+    else:
+        globals()[f"_{extra_name.upper()}_AVAILABLE"] = False
+
+__all__.extend(["_MCP_AVAILABLE", "_AGENT_AVAILABLE"])

pulselink_mcp-0.3.0/pulselink_mcp/__main__.py

@@ -0,0 +1,5 @@
+#!/usr/bin/python
+from pulselink_mcp.agent_server import agent_server
+
+if __name__ == "__main__":
+    agent_server()

pulselink_mcp-0.3.0/pulselink_mcp/agent_data/IDENTITY.md

@@ -0,0 +1,15 @@
+# IDENTITY.md - PulseLink MCP Agent Identity
+
+## [default]
+ * **Name:** PulseLink MCP Agent
+ * **Role:** PulseLink — keyless open-web & social research source (MCP Server + A2A Server)
+ * **Emoji:** 🤖
+
+ ### System Prompt
+ You are the PulseLink MCP Agent.
+ Use the `mcp-client` universal skill and check the reference documentation for
+ `pulselink-mcp.md` to discover the exact tags and tools available for your capabilities.
+
+ ### Capabilities
+ - **MCP Operations**: Leverage the `mcp-client` skill to interact with the target MCP server.
+ - **Custom Agent**: Handle custom tasks or general tasks.

pulselink_mcp-0.3.0/pulselink_mcp/agent_server.py

@@ -0,0 +1,76 @@
+#!/usr/bin/python
+import logging
+import os
+import sys
+import warnings
+
+__version__ = "0.3.0"
+
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+    handlers=[logging.StreamHandler()],
+)
+logger = logging.getLogger(__name__)
+
+
+def agent_server():
+    from agent_utilities import (
+        build_system_prompt_from_workspace,
+        create_agent_parser,
+        create_agent_server,
+        initialize_workspace,
+        load_identity,
+    )
+
+    warnings.filterwarnings("ignore", message=".*urllib3.*or chardet.*")
+    warnings.filterwarnings("ignore", category=DeprecationWarning, module="fastmcp")
+
+    initialize_workspace()
+    meta = load_identity()
+    agent_name = os.getenv("DEFAULT_AGENT_NAME", meta.get("name", "PulseLink MCP"))
+
+    print(f"{agent_name} v{__version__}", file=sys.stderr)
+    parser = create_agent_parser()
+    args = parser.parse_args()
+
+    if args.debug:
+        logging.getLogger().setLevel(logging.DEBUG)
+        logger.debug("Debug mode enabled")
+
+    create_agent_server(
+        mcp_url=args.mcp_url,
+        mcp_config=args.mcp_config or "mcp_config.json",
+        host=args.host,
+        port=args.port,
+        provider=args.provider,
+        model_id=args.model_id,
+        router_model=args.model_id,
+        agent_model=args.model_id,
+        base_url=args.base_url,
+        api_key=args.api_key,
+        agent_description=os.getenv(
+            "AGENT_DESCRIPTION",
+            meta.get(
+                "description",
+                "PulseLink — keyless open-web & social research source (MCP Server + A2A Server)",
+            ),
+        ),
+        system_prompt=os.getenv(
+            "AGENT_SYSTEM_PROMPT",
+            meta.get("content") or build_system_prompt_from_workspace(),
+        ),
+        custom_skills_directory=args.custom_skills_directory,
+        enable_web_ui=args.web,
+        enable_otel=args.otel,
+        otel_endpoint=args.otel_endpoint,
+        otel_headers=args.otel_headers,
+        otel_public_key=args.otel_public_key,
+        otel_secret_key=args.otel_secret_key,
+        otel_protocol=args.otel_protocol,
+        debug=args.debug,
+    )
+
+
+if __name__ == "__main__":
+    agent_server()

pulselink_mcp-0.3.0/pulselink_mcp/api/__init__.py

@@ -0,0 +1,4 @@
+from .api_client_base import ApiClientBase
+from .api_client_pulse import PulseLinkClient
+
+__all__ = ["ApiClientBase", "PulseLinkClient"]

pulselink_mcp-0.3.0/pulselink_mcp/api/api_client_base.py

@@ -0,0 +1,23 @@
+from typing import Any
+
+import requests
+
+
+class ApiClientBase:
+    """Base HTTP API client wrapper."""
+
+    def __init__(self, base_url: str, token: str, verify: bool = True):
+        self.base_url = base_url.rstrip("/")
+        self.token = token
+        self.verify = verify
+        self.session = requests.Session()
+        self.session.headers.update({"Authorization": f"Bearer {token}"})
+
+    def request(self, method: str, path: str, **kwargs) -> dict[str, Any]:
+        url = f"{self.base_url}/{path.lstrip('/')}"
+        response = self.session.request(method, url, verify=self.verify, **kwargs)
+        response.raise_for_status()
+        try:
+            return response.json()
+        except ValueError:
+            return {"status": response.status_code, "text": response.text}

pulselink_mcp-0.3.0/pulselink_mcp/api/api_client_pulse.py

@@ -0,0 +1,43 @@
+"""PulseLink client facade over the source-ladder registry.
+
+CONCEPT:PULSE-001 — the single object the MCP server and agent use. Unlike a
+classic single-endpoint API client, PulseLink fans out across many source ladders
+and authenticates per-source through the shared credential provider, so there is no
+base URL / token here — :func:`pulselink_mcp.auth.get_client` constructs it with no
+configuration and every keyless source works immediately.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ..sources import doctor, get_ladder, list_sources
+
+
+class PulseLinkClient:
+    """Thin facade delegating to the source registry."""
+
+    def sources(self) -> list[str]:
+        return list_sources()
+
+    def search(
+        self, source: str, query: str, cursor: str | None = None, limit: int = 10
+    ) -> dict[str, Any]:
+        return get_ladder(source).search(query, cursor, limit).model_dump()
+
+    def fetch(self, source: str, target: str) -> dict[str, Any]:
+        return get_ladder(source).fetch(target).model_dump()
+
+    def list_items(
+        self, source: str, channel: str, cursor: str | None = None, limit: int = 10
+    ) -> dict[str, Any]:
+        return get_ladder(source).list_items(channel, cursor, limit).model_dump()
+
+    def transcribe(self, target: str, source: str = "youtube") -> dict[str, Any]:
+        return get_ladder(source).transcribe(target).model_dump()
+
+    def status(self) -> dict[str, list[dict[str, Any]]]:
+        return {
+            name: [h.model_dump() for h in backends]
+            for name, backends in doctor().items()
+        }

pulselink_mcp-0.3.0/pulselink_mcp/api_client.py

@@ -0,0 +1,7 @@
+#!/usr/bin/python
+"""Facade re-export of the modular api/ sub-package (backward compatibility)."""
+
+from .api import *  # noqa: F401,F403
+from .api import __all__ as _api_all
+
+__all__ = list(_api_all)

pulselink_mcp-0.3.0/pulselink_mcp/auth.py

@@ -0,0 +1,21 @@
+#!/usr/bin/python
+"""PulseLink client accessor.
+
+PulseLink has no single endpoint: it fans out across many source ladders and
+authenticates per-source through the shared credential provider (OS-5.38). So
+``get_client`` takes no URL/token — it returns a registry-backed facade that works
+keyless out of the box; cookie/official backends light up when their credential
+(``SOURCE_CREDENTIALS``) is present.
+"""
+
+from .api import PulseLinkClient
+
+_client: PulseLinkClient | None = None
+
+
+def get_client() -> PulseLinkClient:
+    """Get or create the singleton PulseLink client facade."""
+    global _client
+    if _client is None:
+        _client = PulseLinkClient()
+    return _client

pulselink_mcp-0.3.0/pulselink_mcp/integrations/__init__.py

@@ -0,0 +1,10 @@
+"""PulseLink integrations — optional capabilities other packages import lazily.
+
+CONCEPT:PULSE-006 — X search/browse tools (xAI/Grok index), externalized from
+agent-utilities so its core carries no X integration. agent-utilities imports
+``x_tools`` from here optionally (try/except ImportError).
+"""
+
+from .x_search_tool import browse_x_post, x_search, x_tools
+
+__all__ = ["x_tools", "x_search", "browse_x_post"]