kensho-kfinance 2.3.0__py3-none-any.whl → 2.4.0__py3-none-any.whl

{kensho_kfinance-2.3.0.dist-info → kensho_kfinance-2.4.0.dist-info}/METADATA

@@ -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.dist-info → kensho_kfinance-2.4.0.dist-info}/RECORD

@@ -1,17 +1,18 @@
-kensho_kfinance-2.3.0.dist-info/licenses/AUTHORS.md,sha256=0h9ClbI0pu1oKj1M28ROUsaxrbZg-6ukQGl6X4y9noI,68
-kensho_kfinance-2.3.0.dist-info/licenses/LICENSE,sha256=bsY4blvSgq6o0FMQ3RXa2NCgco--nHCCchLXzxr6kms,83
-kfinance/CHANGELOG.md,sha256=vIFnA_ArXUrV64T76m3KVMX0wGeVMsEi_u4BmQ3os7Y,1418
+kensho_kfinance-2.4.0.dist-info/licenses/AUTHORS.md,sha256=0h9ClbI0pu1oKj1M28ROUsaxrbZg-6ukQGl6X4y9noI,68
+kensho_kfinance-2.4.0.dist-info/licenses/LICENSE,sha256=bsY4blvSgq6o0FMQ3RXa2NCgco--nHCCchLXzxr6kms,83
+kfinance/CHANGELOG.md,sha256=snsLVUBbhNjIau_BsoWKdxxCAPbPHM_rUQ3pNsseF_k,1446
 kfinance/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 kfinance/batch_request_handling.py,sha256=p6p_G4_BL06GgeKlh7P1k9CUqOMahWCLEw1NoBwbLvU,5698
 kfinance/constants.py,sha256=UuFzqL253-2tRQfma785K9tfaZGv-o821tO2tVLwc5Q,48813
 kfinance/fetch.py,sha256=yaCih8PAkOhVHb3tvmBW0x2w4QmXJiyUATu6Yx-xzP4,23851
 kfinance/kfinance.py,sha256=9lcarUW4fLHJA_U7_1ihCMbNJWs0AztvKf_XEd0qupk,59889
+kfinance/mcp.py,sha256=57OoTrxo5x_v7u1s3WFQNG0LySXyLEGc6CKSVpJLJVw,3717
 kfinance/meta_classes.py,sha256=3V0nSXDDoake5o7kXnrqXuqNIiwI75KR4IYxFqSPhTE,20736
 kfinance/prompt.py,sha256=PtVB8c_FcSlVdyGgByAnIFGzuUuBaEjciCqnBJl1hSQ,25133
 kfinance/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 kfinance/pydantic_models.py,sha256=avpbPqwrAyLqsCbrmFpK_B8_fj1nPlBHrnPxRcBaSkE,774
 kfinance/server_thread.py,sha256=jUnt1YGoYDkqqz1MbCwd44zJs1T_Z2BCgvj75bdtLgA,2574
-kfinance/version.py,sha256=U--yqU7RFo8hQQm8oopUGYLkafj4phNIVfkf5HFEal8,511
+kfinance/version.py,sha256=KyHVhKcn4Ob8_JP09Buz8x5uB4b7RJZLl3FBlZ8sWSY,511
 kfinance/tests/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 kfinance/tests/conftest.py,sha256=voB-w8P_6L3Nel3rdgylXKe5WWaS1q7nCFt1O04uqoY,948
 kfinance/tests/test_batch_requests.py,sha256=uXJF2IcRdyBm5SthwIUHMKtkGZ21MY84pg_k1JeSNOY,11430
@@ -19,6 +20,7 @@ kfinance/tests/test_client.py,sha256=O7icZCSDhlQ9WGhzoXlpiSvbuA-mQNJHBYVsilyP_dE
 kfinance/tests/test_example_notebook.py,sha256=XHwDKw2avyMonTmi3snCcFWNfZhEJOkpBGOZNrMLrhk,6470
 kfinance/tests/test_fetch.py,sha256=nfnz_ZxE-W3KMzpDaRClX55fQJrRjwLTha-rHTallmE,16713
 kfinance/tests/test_group_objects.py,sha256=SoMEZmkG4RYdgWOAwxLHHtzIQho92KM01YbQXPUg578,1689
+kfinance/tests/test_mcp.py,sha256=-pmeZ0PDp8GmXWcrWmaNNqMe7OVZONZLrjA0Y4b82os,594
 kfinance/tests/test_objects.py,sha256=0nDmCFrVcfI8VBo1Ph3YqXNo3uPLsSUiQkjEEHsax1M,30416
 kfinance/tests/test_tools.py,sha256=EWWWyPlGGES8Cn43_VaDAT7Vdp1nlIETE5dtOrP163o,24447
 kfinance/tool_calling/README.md,sha256=omJq7Us6r4U45QB7hRpLjRJ5BMalCkZkh4uXBjTbJXc,2022
@@ -43,7 +45,7 @@ kfinance/tool_calling/get_transcript.py,sha256=eB-IsRwD-mllsMOYRZbH35caQ1Y3teKft
 kfinance/tool_calling/prompts.py,sha256=Yw1DJIMh90cjL-8q6_RMRiSjCtFDXvJAy7QiV5_uAU8,911
 kfinance/tool_calling/resolve_identifier.py,sha256=npslr6bBCu0qEDV1-8d24F5OC3nQ1KBMphuMbHVC1AU,626
 kfinance/tool_calling/shared_models.py,sha256=K-NPQyE_7Ew6Cs0zxG1xO2O47gp5uDHdHtWD7wUDZX4,2132
-kensho_kfinance-2.3.0.dist-info/METADATA,sha256=3rNOXczOABUGLavlhJUmseCJ0pOL6x00uckfLkJcSkI,4066
-kensho_kfinance-2.3.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-kensho_kfinance-2.3.0.dist-info/top_level.txt,sha256=kT_kNwVhfQoOAecY8W7uYah5xaHMoHoAdBIvXh6DaKM,9
-kensho_kfinance-2.3.0.dist-info/RECORD,,
+kensho_kfinance-2.4.0.dist-info/METADATA,sha256=yWX6RmluCSz_qoG7EVTJnKJcsOByeZYXmu3M88-ch2A,5191
+kensho_kfinance-2.4.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+kensho_kfinance-2.4.0.dist-info/top_level.txt,sha256=kT_kNwVhfQoOAecY8W7uYah5xaHMoHoAdBIvXh6DaKM,9
+kensho_kfinance-2.4.0.dist-info/RECORD,,

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
 

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()

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)

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)