kensho-kfinance 2.3.0__tar.gz → 2.4.0__tar.gz

{kensho_kfinance-2.3.0 → kensho_kfinance-2.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kensho-kfinance
-Version: 2.3.0
+Version: 2.4.0
 Summary: Python CLI for kFinance
 Author-email: Luke Brown <luke.brown@kensho.com>, Michelle Keoy <michelle.keoy@kensho.com>, Keith Page <keith.page@kensho.com>, Matthew Rosen <matthew.rosen@kensho.com>, Nick Roshdieh <nick.roshdieh@kensho.com>
 Project-URL: source, https://github.com/kensho-technologies/kfinance
@@ -13,6 +13,8 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 License-File: AUTHORS.md
 Requires-Dist: cachetools<6,>=5.5
+Requires-Dist: click<=9,>=8.2.1
+Requires-Dist: fastmcp<3,>=2
 Requires-Dist: langchain-core>=0.3.15
 Requires-Dist: langchain-google-genai<3,>=2.1.5
 Requires-Dist: numpy>=1.22.4
@@ -52,7 +54,7 @@ Any questions or suggestions can be sent to the [kFinance Maintainers](kfinance-
 
 # Setup
 
-You can install kFinance on [PyPI](https://pypi.org/project/kensho-kfinance/) via 
+You can install kFinance on [PyPI](https://pypi.org/project/kensho-kfinance/) via
 
 `pip install kensho-kfinance`
 
@@ -64,7 +66,7 @@ Once access is obtained, get started using the [Authentication Guide](https://do
 
 To get started, we provide some notebooks:
 
-- The [LLM-ready API Basic Usage](example_notebooks%2Fbasic_usage.ipynb) notebook demonstrates how 
+- The [LLM-ready API Basic Usage](example_notebooks%2Fbasic_usage.ipynb) notebook demonstrates how
 fetch data with the kFinance client.
 - The [tool_calling notebooks](example_notebooks%2Ftool_calling) show how the kFinance library can
 be used for tool calling. We provide notebooks for OpenAI (GPT), Anthropic (Claude), and Google
@@ -73,9 +75,30 @@ wrapper to simplify the integration, and as a lower level non-langchain version.
 
 We also provide an [interactive notebook](example_notebooks/basic_usage.ipynb) that demonstrates some usage examples.
 
+# MCP (Model Context Protocol)
+
+To run the kFinance MCP server use:
+
+`python -m kfinance.mcp`
+
+This function initializes and starts an MCP server that exposes the kFinance tools. The server supports multiple authentication methods and transport protocols to accommodate different deployment scenarios.
+
+The server's full signature is as follows:
+
+`kfinance.mcp [--stdio,-s]/[--sse, ] --refresh-token <refresh-token> --client-id <client-id> --private-key <private-key>`
+
+Authentication Methods (in order of precedence):
+1. Refresh Token: Uses an existing refresh token for authentication. The `--refresh-token <refresh-token>` argument must be provided.
+2. Key Pair: Uses client ID and private key for authentication. Both the `--client-id <client-id>` and `--private-key <private-key>` arguments must be provided.
+3. Browser: Falls back to browser-based authentication flow. This occurs if no auth arguments are provided.
+
+Transport Layers:
+- stdio can be set by passing either `--stdio` or `-s`
+- sse can be set by passing `--sse` or no other transport related flag
+
 # Versioning
-The kFinance uses semantic versioning (major, minor, patch). 
-To bump the version, add a new entry in [CHANGELOG.md](kfinance%2FCHANGELOG.md). 
+The kFinance uses semantic versioning (major, minor, patch).
+To bump the version, add a new entry in [CHANGELOG.md](kfinance%2FCHANGELOG.md).
 This will generate a new version of the library as part of the release process.
 
 # License

{kensho_kfinance-2.3.0 → kensho_kfinance-2.4.0}/README.md

@@ -8,7 +8,7 @@ Any questions or suggestions can be sent to the [kFinance Maintainers](kfinance-
 
 # Setup
 
-You can install kFinance on [PyPI](https://pypi.org/project/kensho-kfinance/) via 
+You can install kFinance on [PyPI](https://pypi.org/project/kensho-kfinance/) via
 
 `pip install kensho-kfinance`
 
@@ -20,7 +20,7 @@ Once access is obtained, get started using the [Authentication Guide](https://do
 
 To get started, we provide some notebooks:
 
-- The [LLM-ready API Basic Usage](example_notebooks%2Fbasic_usage.ipynb) notebook demonstrates how 
+- The [LLM-ready API Basic Usage](example_notebooks%2Fbasic_usage.ipynb) notebook demonstrates how
 fetch data with the kFinance client.
 - The [tool_calling notebooks](example_notebooks%2Ftool_calling) show how the kFinance library can
 be used for tool calling. We provide notebooks for OpenAI (GPT), Anthropic (Claude), and Google
@@ -29,9 +29,30 @@ wrapper to simplify the integration, and as a lower level non-langchain version.
 
 We also provide an [interactive notebook](example_notebooks/basic_usage.ipynb) that demonstrates some usage examples.
 
+# MCP (Model Context Protocol)
+
+To run the kFinance MCP server use:
+
+`python -m kfinance.mcp`
+
+This function initializes and starts an MCP server that exposes the kFinance tools. The server supports multiple authentication methods and transport protocols to accommodate different deployment scenarios.
+
+The server's full signature is as follows:
+
+`kfinance.mcp [--stdio,-s]/[--sse, ] --refresh-token <refresh-token> --client-id <client-id> --private-key <private-key>`
+
+Authentication Methods (in order of precedence):
+1. Refresh Token: Uses an existing refresh token for authentication. The `--refresh-token <refresh-token>` argument must be provided.
+2. Key Pair: Uses client ID and private key for authentication. Both the `--client-id <client-id>` and `--private-key <private-key>` arguments must be provided.
+3. Browser: Falls back to browser-based authentication flow. This occurs if no auth arguments are provided.
+
+Transport Layers:
+- stdio can be set by passing either `--stdio` or `-s`
+- sse can be set by passing `--sse` or no other transport related flag
+
 # Versioning
-The kFinance uses semantic versioning (major, minor, patch). 
-To bump the version, add a new entry in [CHANGELOG.md](kfinance%2FCHANGELOG.md). 
+The kFinance uses semantic versioning (major, minor, patch).
+To bump the version, add a new entry in [CHANGELOG.md](kfinance%2FCHANGELOG.md).
 This will generate a new version of the library as part of the release process.
 
 # License

{kensho_kfinance-2.3.0 → kensho_kfinance-2.4.0}/kensho_kfinance.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kensho-kfinance
-Version: 2.3.0
+Version: 2.4.0
 Summary: Python CLI for kFinance
 Author-email: Luke Brown <luke.brown@kensho.com>, Michelle Keoy <michelle.keoy@kensho.com>, Keith Page <keith.page@kensho.com>, Matthew Rosen <matthew.rosen@kensho.com>, Nick Roshdieh <nick.roshdieh@kensho.com>
 Project-URL: source, https://github.com/kensho-technologies/kfinance
@@ -13,6 +13,8 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 License-File: AUTHORS.md
 Requires-Dist: cachetools<6,>=5.5
+Requires-Dist: click<=9,>=8.2.1
+Requires-Dist: fastmcp<3,>=2
 Requires-Dist: langchain-core>=0.3.15
 Requires-Dist: langchain-google-genai<3,>=2.1.5
 Requires-Dist: numpy>=1.22.4
@@ -52,7 +54,7 @@ Any questions or suggestions can be sent to the [kFinance Maintainers](kfinance-
 
 # Setup
 
-You can install kFinance on [PyPI](https://pypi.org/project/kensho-kfinance/) via 
+You can install kFinance on [PyPI](https://pypi.org/project/kensho-kfinance/) via
 
 `pip install kensho-kfinance`
 
@@ -64,7 +66,7 @@ Once access is obtained, get started using the [Authentication Guide](https://do
 
 To get started, we provide some notebooks:
 
-- The [LLM-ready API Basic Usage](example_notebooks%2Fbasic_usage.ipynb) notebook demonstrates how 
+- The [LLM-ready API Basic Usage](example_notebooks%2Fbasic_usage.ipynb) notebook demonstrates how
 fetch data with the kFinance client.
 - The [tool_calling notebooks](example_notebooks%2Ftool_calling) show how the kFinance library can
 be used for tool calling. We provide notebooks for OpenAI (GPT), Anthropic (Claude), and Google
@@ -73,9 +75,30 @@ wrapper to simplify the integration, and as a lower level non-langchain version.
 
 We also provide an [interactive notebook](example_notebooks/basic_usage.ipynb) that demonstrates some usage examples.
 
+# MCP (Model Context Protocol)
+
+To run the kFinance MCP server use:
+
+`python -m kfinance.mcp`
+
+This function initializes and starts an MCP server that exposes the kFinance tools. The server supports multiple authentication methods and transport protocols to accommodate different deployment scenarios.
+
+The server's full signature is as follows:
+
+`kfinance.mcp [--stdio,-s]/[--sse, ] --refresh-token <refresh-token> --client-id <client-id> --private-key <private-key>`
+
+Authentication Methods (in order of precedence):
+1. Refresh Token: Uses an existing refresh token for authentication. The `--refresh-token <refresh-token>` argument must be provided.
+2. Key Pair: Uses client ID and private key for authentication. Both the `--client-id <client-id>` and `--private-key <private-key>` arguments must be provided.
+3. Browser: Falls back to browser-based authentication flow. This occurs if no auth arguments are provided.
+
+Transport Layers:
+- stdio can be set by passing either `--stdio` or `-s`
+- sse can be set by passing `--sse` or no other transport related flag
+
 # Versioning
-The kFinance uses semantic versioning (major, minor, patch). 
-To bump the version, add a new entry in [CHANGELOG.md](kfinance%2FCHANGELOG.md). 
+The kFinance uses semantic versioning (major, minor, patch).
+To bump the version, add a new entry in [CHANGELOG.md](kfinance%2FCHANGELOG.md).
 This will generate a new version of the library as part of the release process.
 
 # License

{kensho_kfinance-2.3.0 → kensho_kfinance-2.4.0}/kensho_kfinance.egg-info/SOURCES.txt

@@ -39,6 +39,7 @@ kfinance/batch_request_handling.py
 kfinance/constants.py
 kfinance/fetch.py
 kfinance/kfinance.py
+kfinance/mcp.py
 kfinance/meta_classes.py
 kfinance/prompt.py
 kfinance/py.typed
@@ -52,6 +53,7 @@ kfinance/tests/test_client.py
 kfinance/tests/test_example_notebook.py
 kfinance/tests/test_fetch.py
 kfinance/tests/test_group_objects.py
+kfinance/tests/test_mcp.py
 kfinance/tests/test_objects.py
 kfinance/tests/test_tools.py
 kfinance/tool_calling/README.md

{kensho_kfinance-2.3.0 → kensho_kfinance-2.4.0}/kensho_kfinance.egg-info/requires.txt

@@ -1,4 +1,6 @@
 cachetools<6,>=5.5
+click<=9,>=8.2.1
+fastmcp<3,>=2
 langchain-core>=0.3.15
 langchain-google-genai<3,>=2.1.5
 numpy>=1.22.4

{kensho_kfinance-2.3.0 → kensho_kfinance-2.4.0}/kfinance/CHANGELOG.md

@@ -1,5 +1,8 @@
 # Changelog
 
+## v2.4.0
+- Add MCP server
+
 ## v2.3.1
 - Add llm tools for retrieving earnings and transcripts
 

kensho_kfinance-2.4.0/kfinance/mcp.py

@@ -0,0 +1,101 @@
+from textwrap import dedent
+from typing import Literal, Optional
+
+import click
+from fastmcp import FastMCP
+from fastmcp.utilities.logging import get_logger
+
+from kfinance.kfinance import Client
+from kfinance.tool_calling.shared_models import KfinanceTool
+
+
+logger = get_logger(__name__)
+
+
+def build_doc_string(tool: KfinanceTool) -> str:
+    """Build a formatted documentation string for a Kfinance tool.
+
+    This function takes a KfinanceTool object and constructs a comprehensive
+    documentation string that includes the tool's description and detailed
+    information about its arguments, including default values and descriptions.
+
+    :param tool: The Kfinance tool object containing metadata about the tool's functionality, description, and argument schema.
+    :type tool: KfinanceTool
+    :return: A formatted documentation string containing for the tool description with detailed argument information.
+    :rtype: str
+    """
+
+    description = dedent(f"""
+        {tool.description}
+
+        Args:
+    """).strip()
+
+    for arg_name, arg_field in tool.args_schema.model_fields.items():
+        default_value_description = (
+            f"Default: {arg_field.default}. " if not arg_field.is_required() else ""
+        )
+        param_description = f"\n    {arg_name}: {default_value_description}{arg_field.description}"
+        description += param_description
+
+    return description
+
+
+@click.command()
+@click.option("--stdio/--sse", "-s/ ", default=False)
+@click.option("--refresh-token", required=False)
+@click.option("--client-id", required=False)
+@click.option("--private-key", required=False)
+def run_mcp(
+    stdio: bool,
+    refresh_token: Optional[str] = None,
+    client_id: Optional[str] = None,
+    private_key: Optional[str] = None,
+) -> None:
+    """Run the Kfinance MCP server with specified configuration.
+
+    This function initializes and starts an MCP server that exposes Kfinance
+    tools. The server supports multiple authentication methods and
+    transport protocols to accommodate different deployment scenarios.
+
+    Authentication Methods (in order of precedence):
+    1. Refresh Token: Uses an existing refresh token for authentication
+    2. Key Pair: Uses client ID and private key for authentication
+    3. Browser: Falls back to browser-based authentication flow
+
+    :param stdio: If True, use STDIO transport; if False, use SSE transport.
+    :type stdio: bool
+    :param refresh_token: OAuth refresh token for authentication
+    :type refresh_token: str
+    :param client_id: Client id for key-pair authentication
+    :type client_id: str
+    :param private_key: Private key for key-pair authentication.
+    :type private_key: str
+    """
+    transport: Literal["stdio", "sse"] = "stdio" if stdio else "sse"
+    logger.info("Sever will run with %s transport", transport)
+    if refresh_token:
+        logger.info("The client will be authenticated using a refresh token")
+        kfinance_client = Client(refresh_token=refresh_token)
+    elif client_id and private_key:
+        logger.info("The client will be authenticated using a key pair")
+        kfinance_client = Client(client_id=client_id, private_key=private_key)
+    else:
+        logger.info("The client will be authenticated using a browser")
+        kfinance_client = Client()
+
+    kfinance_mcp: FastMCP = FastMCP("Kfinance")
+    for tool in kfinance_client.langchain_tools:
+        logger.info("Adding %s to server", tool.name)
+        kfinance_mcp.tool(
+            name_or_fn=getattr(tool, "_run"),
+            name=tool.name,
+            description=build_doc_string(tool),
+        )
+
+    logger.info("Server starting")
+    kfinance_mcp.run(transport=transport)
+
+
+if __name__ == "__main__":
+    run_mcp()

kensho_kfinance-2.4.0/kfinance/tests/test_mcp.py

@@ -0,0 +1,16 @@
+from typing import Type
+
+import pytest
+
+from kfinance.kfinance import Client
+from kfinance.mcp import build_doc_string
+from kfinance.tool_calling import ALL_TOOLS
+from kfinance.tool_calling.shared_models import KfinanceTool
+
+
+class TestDocStringBuilding:
+    @pytest.mark.parametrize("tool_class", ALL_TOOLS)
+    def test_build_doc_string(self, mock_client: Client, tool_class: Type[KfinanceTool]):
+        """This test build the docstring for each tool. A success is considered if no exception is raised"""
+        tool = tool_class(kfinance_client=mock_client)
+        build_doc_string(tool)

{kensho_kfinance-2.3.0 → kensho_kfinance-2.4.0}/kfinance/version.py

@@ -17,5 +17,5 @@ __version__: str
 __version_tuple__: VERSION_TUPLE
 version_tuple: VERSION_TUPLE
 
-__version__ = version = '2.3.0'
-__version_tuple__ = version_tuple = (2, 3, 0)
+__version__ = version = '2.4.0'
+__version_tuple__ = version_tuple = (2, 4, 0)

{kensho_kfinance-2.3.0 → kensho_kfinance-2.4.0}/pyproject.toml

@@ -19,6 +19,8 @@ classifiers = [
 
 dependencies = [
     "cachetools>=5.5,<6",
+    "click>=8.2.1,<=9",
+    "fastmcp>=2,<3",
     "langchain-core>=0.3.15",
     "langchain-google-genai>=2.1.5,<3",
     "numpy>=1.22.4",