source-context-mcp 0.1.dev3__tar.gz → 0.1.dev5__tar.gz

source_context_mcp-0.1.dev5/PKG-INFO

@@ -0,0 +1,209 @@
+Metadata-Version: 2.3
+Name: source-context-mcp
+Version: 0.1.dev5
+Summary: Local Model Context Protocol (MCP) server for Source Context code intelligence.
+Author: Le Ngoc Tu, Dang Huu Hieu, Huynh Phat Tai
+Author-email: Le Ngoc Tu <tuleaibk@gmail.com>, Dang Huu Hieu <danghuuhieu038@gmail.com>, Huynh Phat Tai <huynhphtai@gmail.com>
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: mcp[cli]>=2.0.0
+Requires-Dist: pydantic>=2.13.4
+Requires-Dist: pydantic-settings>=2.14.2
+Requires-Dist: tomli-w>=1.2.0
+Requires-Dist: typer>=0.27.0
+Requires-Python: >=3.12
+Project-URL: Repository, https://github.com/TuLe142857/source-context
+Description-Content-Type: text/markdown
+
+# Table of Contents
+- [Introduction](#intro)
+- [Requirements](#requirements)
+- [Setup API Server](#setup-api-server)
+- [Setup MCP Server](#setup-mcp-server)
+- [Available CLI Commands](#available-cli-commands)
+- [Available MCP Capabilities](#available-mcp-capabilities)
+  - [Tools](#tools)
+  - [Resources](#resources)
+  - [Prompts](#prompts)
+
+# Introduction <a name="intro"></a>
+This MCP server runs on your local machine and communicates over the `stdio` (Standard Input/Output) transport - meaning
+it talks to your coding agent through standard input/output streams rather than over the network.
+
+The server is published to `PyPI`, so you can run it directly with the `uvx` command, without a
+manual installation step.
+- Package name: `source-context-mcp`
+- For more details: https://pypi.org/project/source-context-mcp/
+
+This MCP server does not analyze your source code by itself. It is a thin bridge:
+ - It receives tool calls from your coding agent.
+ - It forwards those calls, with your credentials, to a REST API server.
+ - That API server is the one actually indexing and analyzing your codebase, and it returns the results back through
+the MCP server to your agent.
+
+So before using this MCP server, you need that REST API server up and running (locally or publicly hosted).
+
+```mermaid
+flowchart
+    Agents["Coding Agents (Claude, Antigravity, ...)"]
+    MCP["This MCP Server"]
+    API["REST API Server (locally or publicly hosted)"]
+    
+    Agents --> MCP
+    MCP --> API
+```
+
+# Requirements <a name="requirements"></a>
+- uv: a Python package manager, used to run this MCP locally via the `uvx` command (similar in spirit to `npx` for
+Node.js packages).
+- Python version: 3.12+
+- A running REST API server with authentication enabled — see [Setup MCP Server](#setup-mcp-server) below for setup.
+
+# Setup API Server <a name="setup-api-server"></a>
+See: https://github.com/TuLe142857/source-context
+
+This server manages your team workspace (a workspace can contain many repositories), handles indexing, analyzes the
+codebase, and exposes the REST API that this MCP server calls. You can host it on your local machine or make it public
+on the internet.
+
+# Setup MCP Server <a name="setup-mcp-server"></a>
+## Step 1: Get your Personal Access Token
+Log in to your REST API server and generate a PAT (Personal Access Token) from your account settings. This token
+authenticates the MCP server's requests to the API on your behalf - treat it like a password.
+
+## Step 2: Configure the MCP Server
+You have two ways to set the configuration:
+
+**Option A — CLI command:**  
+```shell
+uvx source-context-mcp config \
+  --token <your token> \
+  --server-url <server_url>
+```
+Security note: this command may save your token in your shell's command history. 
+Prefer Option B below if that's a concern for you.
+
+**Option B (recommended) — edit the config file directly:**  
+Edit `~/.source_context_mcp/config.toml` (Linux/macOS) or `C:\Users\{username}\.source_context_mcp\config.toml` (Windows):
+```toml
+SERVER_URL = "http://localhost:8000/mcp/v1"
+PAT = "your token"
+```
+
+## Step 3: Add MCP server to your coding agent
+This package is published to PyPI, so it can be run via `uvx source-context-mcp run`. It uses `typer` to wrap the MCP
+server as a CLI (Command-Line Interface), so besides `run` it also exposes utility commands like `config`, `show-config`,
+and `config-dir` - see [Available CLI Commands](#available-cli-commands) below.
+
+### Antigravity (IDE & CLI)
+Global scope - Edit `~/.gemini/config/mcp_config.json` (Linux/macOS) or
+`C:\Users\{username}\.gemini\config\mcp_config.json` (Windows):
+```json
+{
+    "mcpServers": {
+        "source-context-mcp": {
+            "command": "uvx",
+            "args": ["source-context-mcp", "run"]
+        }
+    }
+}
+```
+
+Project scope - Edit `.agents/mcp_config.json`:
+```json
+{
+    "mcpServers": {
+        "source-context-mcp": {
+            "command": "uvx",
+            "args": ["source-context-mcp", "run"]
+        }
+    }
+}
+```
+
+### Claude Code
+Global scope:
+```shell
+claude mcp add --scope user source-context-mcp -- uvx source-context-mcp run
+```
+
+Project scope - The following command writes to `.mcp.json`, which is shared with your team when committed to git:
+```shell
+claude mcp add --scope project source-context-mcp -- uvx source-context-mcp run
+```
+
+Local scope - Not shared with your team:
+```shell
+claude mcp add  source-context-mcp -- uvx source-context-mcp run
+```
+
+### Other Agents
+If you're using a different coding agent, check its documentation for how to add a local MCP server over the `stdio`
+transport. Most agents accept a generic JSON block like this:
+
+```json
+{
+    "mcpServers": {
+        "source-context-mcp": {
+            "command": "uvx",
+            "args": ["source-context-mcp", "run"]
+        }
+    }
+}
+```
+
+# Available CLI Commands <a name="available-cli-commands"></a>
+The package installs a `source-context-mcp` CLI (built with `typer`). Run `uvx source-context-mcp --help` at any time
+to see this list from the tool itself.
+
+| Command       | Description                                                                        | Options                                                                                                      |
+|---------------|------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------|
+| `run`         | Run the MCP server over the `stdio` transport.                                     | `--server-url <url>`, `--token <token>`, `--workspace-id <id>` - override the saved config for this run only |
+| `config`      | Save configuration (server URL, token, default workspace ID) to the config file.   | `--server-url <url>`, `--token <token>`, `--workspace-id <id>`                                               |
+| `show-config` | Print the current configuration. Secret values (e.g. the token) are masked as `*`. |                                                                                                              |
+| `config-dir`  | Print the path to the configuration directory.                                     |                                                                                                              |
+
+Global option (on the base `source-context-mcp` command):
+- `--version` / `-v` - print the installed package version and exit.
+
+# Available MCP Capabilities <a name="available-mcp-capabilities"></a>
+
+## Tools <a name="tools"></a>
+Tools are like functions that this MCP server exposes to your coding agent. This server provides the following tools:
+
+### General
+- `list_workspaces()` - List all workspaces accessible to the current user.
+- `get_path_settings(path)` - Get the default workspace and repository settings configured for a local path.
+- `default_workspace()` - Get the server-configured default workspace ID, used when the current path has no path-specific default.
+- `list_repositories(workspace_id)` - List all repositories in a workspace.
+- `list_branches(workspace_id, repository_id)` - List all branches in a repository.
+- `list_projects(workspace_id, repository_id, branch_name)` - List all projects on a branch.
+
+### Graph (code structure & relationships)
+- `list_files_in_project(project_id)` - List all files in a project.
+- `get_file_structure(file_id)` - Get a file's structure: classes and methods.
+- `get_file_content(file_id)` - Read a file's full content.
+- `get_node_info(node_id)` - Get node metadata: id, name, file_id, position in file.
+- `get_node_content(node_id)` - Get a node's source content.
+- `find_node_usages(node_id)` - Find all nodes that call or reference the specified node.
+- `find_node_callees(node_id)` - Find all nodes that the specified node calls or references.
+- `find_node_by_name(name, node_type)` - *Not implemented yet.*
+
+### Vector (semantic search)
+- `search_in_workspace(query, workspace_id, top_k)` - Semantic search across all repositories and branches in a workspace.
+- `search_in_repo_and_branch(repository_id, branch_name, query, top_k)` - Semantic search scoped to a specific repository and branch.
+
+> Note: development builds (versions containing `dev`) also register an internal `debug` tool for inspecting the
+> server's configuration. It is not available in stable releases.
+
+## Resources <a name="resources"></a>
+Not implemented yet.
+
+## Prompts <a name="prompts"></a>
+Prompts are reusable, pre-written instructions your coding agent can pull in as a starting point for a task. This
+server provides the following prompts:
+
+- `analyze_architecture(project)` - Analyze the software architecture of the given project: locate it, inspect its
+file/project structure, and trace dependencies to produce a structured architecture summary.
+- `prepare_for_change()` - Intended for use before refactoring, to look up usages of a function, class, or other
+object and assess the blast radius of a change. *(work in progress)*
+- `summarize_file()` - Summarize a file. *(work in progress)*

source_context_mcp-0.1.dev5/README.md

@@ -0,0 +1,193 @@
+# Table of Contents
+- [Introduction](#intro)
+- [Requirements](#requirements)
+- [Setup API Server](#setup-api-server)
+- [Setup MCP Server](#setup-mcp-server)
+- [Available CLI Commands](#available-cli-commands)
+- [Available MCP Capabilities](#available-mcp-capabilities)
+  - [Tools](#tools)
+  - [Resources](#resources)
+  - [Prompts](#prompts)
+
+# Introduction <a name="intro"></a>
+This MCP server runs on your local machine and communicates over the `stdio` (Standard Input/Output) transport - meaning
+it talks to your coding agent through standard input/output streams rather than over the network.
+
+The server is published to `PyPI`, so you can run it directly with the `uvx` command, without a
+manual installation step.
+- Package name: `source-context-mcp`
+- For more details: https://pypi.org/project/source-context-mcp/
+
+This MCP server does not analyze your source code by itself. It is a thin bridge:
+ - It receives tool calls from your coding agent.
+ - It forwards those calls, with your credentials, to a REST API server.
+ - That API server is the one actually indexing and analyzing your codebase, and it returns the results back through
+the MCP server to your agent.
+
+So before using this MCP server, you need that REST API server up and running (locally or publicly hosted).
+
+```mermaid
+flowchart
+    Agents["Coding Agents (Claude, Antigravity, ...)"]
+    MCP["This MCP Server"]
+    API["REST API Server (locally or publicly hosted)"]
+    
+    Agents --> MCP
+    MCP --> API
+```
+
+# Requirements <a name="requirements"></a>
+- uv: a Python package manager, used to run this MCP locally via the `uvx` command (similar in spirit to `npx` for
+Node.js packages).
+- Python version: 3.12+
+- A running REST API server with authentication enabled — see [Setup MCP Server](#setup-mcp-server) below for setup.
+
+# Setup API Server <a name="setup-api-server"></a>
+See: https://github.com/TuLe142857/source-context
+
+This server manages your team workspace (a workspace can contain many repositories), handles indexing, analyzes the
+codebase, and exposes the REST API that this MCP server calls. You can host it on your local machine or make it public
+on the internet.
+
+# Setup MCP Server <a name="setup-mcp-server"></a>
+## Step 1: Get your Personal Access Token
+Log in to your REST API server and generate a PAT (Personal Access Token) from your account settings. This token
+authenticates the MCP server's requests to the API on your behalf - treat it like a password.
+
+## Step 2: Configure the MCP Server
+You have two ways to set the configuration:
+
+**Option A — CLI command:**  
+```shell
+uvx source-context-mcp config \
+  --token <your token> \
+  --server-url <server_url>
+```
+Security note: this command may save your token in your shell's command history. 
+Prefer Option B below if that's a concern for you.
+
+**Option B (recommended) — edit the config file directly:**  
+Edit `~/.source_context_mcp/config.toml` (Linux/macOS) or `C:\Users\{username}\.source_context_mcp\config.toml` (Windows):
+```toml
+SERVER_URL = "http://localhost:8000/mcp/v1"
+PAT = "your token"
+```
+
+## Step 3: Add MCP server to your coding agent
+This package is published to PyPI, so it can be run via `uvx source-context-mcp run`. It uses `typer` to wrap the MCP
+server as a CLI (Command-Line Interface), so besides `run` it also exposes utility commands like `config`, `show-config`,
+and `config-dir` - see [Available CLI Commands](#available-cli-commands) below.
+
+### Antigravity (IDE & CLI)
+Global scope - Edit `~/.gemini/config/mcp_config.json` (Linux/macOS) or
+`C:\Users\{username}\.gemini\config\mcp_config.json` (Windows):
+```json
+{
+    "mcpServers": {
+        "source-context-mcp": {
+            "command": "uvx",
+            "args": ["source-context-mcp", "run"]
+        }
+    }
+}
+```
+
+Project scope - Edit `.agents/mcp_config.json`:
+```json
+{
+    "mcpServers": {
+        "source-context-mcp": {
+            "command": "uvx",
+            "args": ["source-context-mcp", "run"]
+        }
+    }
+}
+```
+
+### Claude Code
+Global scope:
+```shell
+claude mcp add --scope user source-context-mcp -- uvx source-context-mcp run
+```
+
+Project scope - The following command writes to `.mcp.json`, which is shared with your team when committed to git:
+```shell
+claude mcp add --scope project source-context-mcp -- uvx source-context-mcp run
+```
+
+Local scope - Not shared with your team:
+```shell
+claude mcp add  source-context-mcp -- uvx source-context-mcp run
+```
+
+### Other Agents
+If you're using a different coding agent, check its documentation for how to add a local MCP server over the `stdio`
+transport. Most agents accept a generic JSON block like this:
+
+```json
+{
+    "mcpServers": {
+        "source-context-mcp": {
+            "command": "uvx",
+            "args": ["source-context-mcp", "run"]
+        }
+    }
+}
+```
+
+# Available CLI Commands <a name="available-cli-commands"></a>
+The package installs a `source-context-mcp` CLI (built with `typer`). Run `uvx source-context-mcp --help` at any time
+to see this list from the tool itself.
+
+| Command       | Description                                                                        | Options                                                                                                      |
+|---------------|------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------|
+| `run`         | Run the MCP server over the `stdio` transport.                                     | `--server-url <url>`, `--token <token>`, `--workspace-id <id>` - override the saved config for this run only |
+| `config`      | Save configuration (server URL, token, default workspace ID) to the config file.   | `--server-url <url>`, `--token <token>`, `--workspace-id <id>`                                               |
+| `show-config` | Print the current configuration. Secret values (e.g. the token) are masked as `*`. |                                                                                                              |
+| `config-dir`  | Print the path to the configuration directory.                                     |                                                                                                              |
+
+Global option (on the base `source-context-mcp` command):
+- `--version` / `-v` - print the installed package version and exit.
+
+# Available MCP Capabilities <a name="available-mcp-capabilities"></a>
+
+## Tools <a name="tools"></a>
+Tools are like functions that this MCP server exposes to your coding agent. This server provides the following tools:
+
+### General
+- `list_workspaces()` - List all workspaces accessible to the current user.
+- `get_path_settings(path)` - Get the default workspace and repository settings configured for a local path.
+- `default_workspace()` - Get the server-configured default workspace ID, used when the current path has no path-specific default.
+- `list_repositories(workspace_id)` - List all repositories in a workspace.
+- `list_branches(workspace_id, repository_id)` - List all branches in a repository.
+- `list_projects(workspace_id, repository_id, branch_name)` - List all projects on a branch.
+
+### Graph (code structure & relationships)
+- `list_files_in_project(project_id)` - List all files in a project.
+- `get_file_structure(file_id)` - Get a file's structure: classes and methods.
+- `get_file_content(file_id)` - Read a file's full content.
+- `get_node_info(node_id)` - Get node metadata: id, name, file_id, position in file.
+- `get_node_content(node_id)` - Get a node's source content.
+- `find_node_usages(node_id)` - Find all nodes that call or reference the specified node.
+- `find_node_callees(node_id)` - Find all nodes that the specified node calls or references.
+- `find_node_by_name(name, node_type)` - *Not implemented yet.*
+
+### Vector (semantic search)
+- `search_in_workspace(query, workspace_id, top_k)` - Semantic search across all repositories and branches in a workspace.
+- `search_in_repo_and_branch(repository_id, branch_name, query, top_k)` - Semantic search scoped to a specific repository and branch.
+
+> Note: development builds (versions containing `dev`) also register an internal `debug` tool for inspecting the
+> server's configuration. It is not available in stable releases.
+
+## Resources <a name="resources"></a>
+Not implemented yet.
+
+## Prompts <a name="prompts"></a>
+Prompts are reusable, pre-written instructions your coding agent can pull in as a starting point for a task. This
+server provides the following prompts:
+
+- `analyze_architecture(project)` - Analyze the software architecture of the given project: locate it, inspect its
+file/project structure, and trace dependencies to produce a structured architecture summary.
+- `prepare_for_change()` - Intended for use before refactoring, to look up usages of a function, class, or other
+object and assess the blast radius of a change. *(work in progress)*
+- `summarize_file()` - Summarize a file. *(work in progress)*

{source_context_mcp-0.1.dev3 → source_context_mcp-0.1.dev5}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "source-context-mcp"
-version = "0.1.dev3"
+version = "0.1.dev5"
 description = "Local Model Context Protocol (MCP) server for Source Context code intelligence."
 readme = "README.md"
 requires-python = ">=3.12"

{source_context_mcp-0.1.dev3 → source_context_mcp-0.1.dev5}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "source-context-mcp"
-version = "0.1.dev3"
+version = "0.1.dev5"
 description = "Local Model Context Protocol (MCP) server for Source Context code intelligence."
 readme = "README.md"
 authors = [

{source_context_mcp-0.1.dev3 → source_context_mcp-0.1.dev5}/src/source_context_mcp/cli.py

@@ -1,8 +1,7 @@
-import importlib.metadata
-
 import typer
 
-from .core.settings import CONFIG_FILE, get_settings, get_settings_with_overrides, write_settings
+from .core.metadata import get_package_version
+from .core.settings import CONFIG_DIR, CONFIG_FILE, get_settings, get_settings_with_overrides, write_settings
 from .server import create_server
 
 cli = typer.Typer()
@@ -51,9 +50,14 @@ def show_config():
     typer.echo(settings_json)
 
 
+@cli.command(name="config-dir", help="Show the MCP server's configuration directory")
+def show_config_dir():
+    typer.echo(CONFIG_DIR)
+
+
 @cli.callback(invoke_without_command=True)
 def version_check(
     version: bool = typer.Option(False, "--version", "-v", help="Show version"),
 ):
     if version:
-        typer.echo(importlib.metadata.version("source-context-mcp"))
+        typer.echo(get_package_version())

source_context_mcp-0.1.dev5/src/source_context_mcp/core/metadata.py

@@ -0,0 +1,16 @@
+import importlib.metadata
+from functools import lru_cache
+
+_PACKAGE_NAME = "source-context-mcp"
+
+
+@lru_cache
+def get_package_version() -> str:
+    """
+    Get package version.
+    Read from ``pyproject.toml`` file.
+
+    Returns:
+        This package version.
+    """
+    return importlib.metadata.version("source-context-mcp")

{source_context_mcp-0.1.dev3 → source_context_mcp-0.1.dev5}/src/source_context_mcp/core/settings.py

@@ -14,17 +14,20 @@ class Settings(BaseSettings):
         toml_file=str(CONFIG_FILE),
     )
 
-    SERVER_URL: str = "default"
-    """Server URL. Include prefix. Example: http://localhost:8000/mcp/v1"""
+    SERVER_URL: str = "http://localhost:8000/mcp/v1"
+    """Server URL. Include prefix. Default: http://localhost:8000/mcp/v1"""
 
     PAT: SecretStr = SecretStr("Default")
     """Personal access token"""
 
-    DEFAULT_WORKSPACE_ID: int = 1
+    DEFAULT_WORKSPACE_ID: int | None = None
     """Default Workspace ID"""
 
     PATH_WORKSPACE: dict[str, int] = {}
+    """Map [path, default_workspace_id]]"""
+
     PATH_REPO: dict[str, int] = {}
+    """Map [path, default_repo_id]]"""
 
     @classmethod
     def settings_customise_sources(
@@ -85,6 +88,8 @@ def write_settings(settings: Settings):
         "SERVER_URL": settings.SERVER_URL,
         "PAT": settings.PAT.get_secret_value(),
         "DEFAULT_WORKSPACE_ID": settings.DEFAULT_WORKSPACE_ID,
+        "PATH_WORKSPACE": settings.PATH_WORKSPACE,
+        "PATH_REPO": settings.PATH_REPO,
     }
 
     with CONFIG_FILE.open("wb") as f:

source_context_mcp-0.1.dev5/src/source_context_mcp/prompts/__init__.py

@@ -0,0 +1,19 @@
+from mcp.server import MCPServer
+
+from .analyze_architecture import register_prompts as register_analyze_architecture
+from .prepare_for_change import register_prompts as register_prepare_for_change
+from .summarize_file import register_prompts as register_summarize_file
+
+
+def register_prompts(mcp: MCPServer) -> None:
+    """
+    Register prompts for MCP server
+    Args:
+        mcp: MCPServer instance
+    """
+    register_analyze_architecture(mcp)
+    register_prepare_for_change(mcp)
+    register_summarize_file(mcp)
+
+
+__all__ = ["register_prompts"]

source_context_mcp-0.1.dev5/src/source_context_mcp/prompts/analyze_architecture.py

@@ -0,0 +1,30 @@
+from typing import Annotated
+
+from mcp.server import MCPServer
+from pydantic import Field
+
+
+def register_prompts(mcp: MCPServer):
+    @mcp.prompt(
+        description="Analyze the software architecture of the given project",
+    )
+    def analyze_architecture(project: Annotated[str, Field(description="Project name")]):
+        return f"""
+Analyze the software architecture of the project: '{project}'.
+
+Step 1:Identify the Project:
+ - If the exact project location or repository is unclear, use tools such as `list_projects`, `list_repositories`, \
+ or `list_branches` to locate and confirm the target project.
+
+Step 2: Analyze Project Structure (Token-Efficient Approach):
+ - Start by calling `get_file_structure` (or `list_files`) to inspect the directory layout.
+ - *Best Practice*: Always prefer `get_file_structure` first, as it returns only the structure without full source \
+ code, conserving API tokens.
+ - Only call `get_file_content` for specific files when you need detailed implementation insights.
+
+Step 3: Deepen Architecture Analysis(If needed):
+ - Depending on the architecture aspects you are investigating, use additional tools such as `find_node_usages`, \
+ `find_node_callees`, or any other relevant analysis tools to trace dependencies and data flow.
+
+Provide a clear, structured summary of the architectural patterns, key components, and relationships found in the \
+project."""

source_context_mcp-0.1.dev5/src/source_context_mcp/prompts/prepare_for_change.py

@@ -0,0 +1,49 @@
+from typing import Annotated
+
+from mcp.server import MCPServer
+from pydantic import Field
+
+
+def register_prompts(mcp: MCPServer):
+    @mcp.prompt(
+        description="Use when refactor code. Look for object(function, class, ...) usage to detect refactor effect"
+    )
+    def prepare_for_change(
+        target: Annotated[
+            str, Field(description="Name of the function, class, method, or variable you are about to change.")
+        ],
+        project: Annotated[str, Field(description="Project name where the target is located, if known.")] = "",
+        change_description: Annotated[
+            str, Field(description="Optional description of the change you intend to make.")
+        ] = "",
+    ):
+        change_note = f"\nIntended change: {change_description}\n" if change_description else ""
+        project_note = f" in project '{project}'" if project else ""
+
+        return f"""
+Prepare for a change to '{target}'{project_note}.{change_note}
+
+Step 1: Locate the Target:
+ - If the exact project, file, or node is unclear, use `list_projects`, `list_repositories`, `list_branches`, or \
+ semantic search (`search_in_workspace` / `search_in_repo_and_branch`) to find it.
+ - Once the project is known, prefer `list_files_in_project` and `get_file_structure` to locate the node without \
+ reading full file contents.
+ - Use `get_node_info` to confirm you have the right node before proceeding.
+
+Step 2: Understand the Current Implementation:
+ - Call `get_node_content` on the target node to review its current signature and behavior.
+
+Step 3: Assess the Blast Radius:
+ - Call `find_node_usages` on the target node to list every node that calls or references it. This is the primary \
+ signal for how risky the change is - the more usages, the wider the blast radius.
+ - For each usage that could be affected (e.g. call sites depending on a changed signature, return type, or \
+ behavior), inspect it with `get_node_content` or `get_file_content` to understand exactly how the target is used.
+
+Step 4: Check Internal Dependencies (if the change affects internal logic):
+ - Call `find_node_callees` on the target node to see what it depends on, so you don't break assumptions the \
+ target relies on.
+
+Step 5: Summarize:
+ - List every affected file/node found in Step 3.
+ - Flag usages that are likely to break or need updating given the intended change.
+ - Recommend what should be tested or reviewed before making the change."""

source_context_mcp-0.1.dev5/src/source_context_mcp/prompts/summarize_file.py

@@ -0,0 +1,33 @@
+from typing import Annotated
+
+from mcp.server import MCPServer
+from pydantic import Field
+
+
+def register_prompts(mcp: MCPServer):
+    @mcp.prompt(description="Summarize file")
+    def summarize_file(
+        file: Annotated[str, Field(description="File path or file name to summarize.")],
+        project: Annotated[
+            str, Field(description="Project name the file belongs to, to help locate it if the path is ambiguous.")
+        ] = "",
+    ):
+        project_note = f" in project '{project}'" if project else ""
+
+        return f"""
+Summarize the file '{file}'{project_note}.
+
+Step 1: Locate the File:
+ - If the exact project or file ID is unclear, use `list_projects` to find the project, then `list_files_in_project` \
+ to find the matching file.
+
+Step 2: Inspect Structure (Token-Efficient Approach):
+ - Start with `get_file_structure` to see the file's classes, methods, and functions without reading the full \
+ source.
+ - Only call `get_file_content` if you need the actual implementation details to write an accurate summary.
+
+Step 3: Summarize:
+ - State the file's purpose and its role within the project.
+ - List its main classes/functions and what each one does, at a high level.
+ - Note any notable dependencies or relationships to other parts of the codebase (use `find_node_usages` or \
+ `find_node_callees` on specific nodes only if that context is needed)."""

source_context_mcp-0.1.dev5/src/source_context_mcp/resources/__init__.py

@@ -0,0 +1,11 @@
+from mcp.server import MCPServer
+
+
+def register_resources(mcp: MCPServer):
+    """
+    Currently not implemented
+    """
+    pass
+
+
+__all__ = ["register_resources"]

source_context_mcp-0.1.dev5/src/source_context_mcp/server.py

@@ -0,0 +1,92 @@
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+
+from mcp.server import MCPServer
+
+from source_context_mcp.core import ApiClient, AppContext, get_settings_with_overrides
+from source_context_mcp.core.metadata import get_package_version
+from source_context_mcp.prompts import register_prompts
+from source_context_mcp.resources import register_resources
+from source_context_mcp.tools import register_tools
+
+SERVER_DESCRIPTION = """
+SourceContextMCP is an MCP server that gives AI coding assistants structured, queryable access to indexed source code \
+across workspaces, repositories, branches, and projects. It exposes tools to browse project/file structure, read file \
+and code-node content, traverse call/reference graphs between code nodes, and run semantic (vector) search over a \
+codebase — letting an agent explore and understand large, multi-repository codebases without needing direct local file \
+access."
+"""
+
+SERVER_INSTRUCTIONS = """
+SourceContextMCP gives read-only access to a pre-indexed source of truth for one or more codebases, organized as: \
+workspace -> repository -> branch -> project -> file -> node (class/method/function/variable/...).
+
+Most tools require one or more IDs (workspace_id, repository_id, project_id, file_id, node_id). These are opaque and \
+server-assigned - never guess them. Always obtain them from the matching listing tool or reuse an ID from a previous \
+call.
+
+Resolve scope before calling graph or search tools. Try get_path_settings(path) first if the user is working inside a \
+local checkout; fall back to default_workspace() if no path-specific config exists. Otherwise narrow down with \
+list_workspaces -> list_repositories -> list_branches -> list_projects.
+
+Once you have a project_id, use list_files_in_project for file_ids, then get_file_structure before get_file_content \
+when you only need an overview or a node_id - avoid reading full file contents unless necessary.
+
+For call-graph relationships on a node_id: use find_node_usages before renaming or changing a signature to assess \
+blast radius, and find_node_callees to understand what a symbol depends on. Prefer graph traversal over semantic \
+search when you need precise, complete relationships - semantic search is approximate and may miss or over-return \
+results.
+
+Use search_in_workspace or search_in_repo_and_branch (prefer the latter when repository/branch is already known - more \
+precise) when you don't know exact file/node names. Treat semantic search as an entry point, then switch to graph \
+tools for precise structured details.
+"""
+
+
+def make_life_span(
+    base_url_override: str | None = None, pat_override: str | None = None, workspace_id_override: int | None = None
+):
+    @asynccontextmanager
+    async def server_lifespan(app: MCPServer) -> AsyncIterator[AppContext]:
+        settings = get_settings_with_overrides(
+            server_url_override=base_url_override,
+            pat_override=pat_override,
+            default_workspace_id_override=workspace_id_override,
+        )
+
+        yield AppContext(
+            api_client=ApiClient(base_url=settings.SERVER_URL, token=settings.PAT.get_secret_value()), settings=settings
+        )
+
+    return server_lifespan
+
+
+def create_server(
+    base_url_override: str | None = None, pat_override: str | None = None, workspace_id_override: int | None = None
+) -> MCPServer:
+    """
+    Create an MCPServer instance.
+
+    Args:
+        base_url_override: override default server URL
+        pat_override: override default Personal Access Token
+        workspace_id_override: override default workspace ID
+    """
+
+    life_span = make_life_span(
+        base_url_override=base_url_override, pat_override=pat_override, workspace_id_override=workspace_id_override
+    )
+
+    server = MCPServer(
+        name="source-context-mcp",
+        lifespan=life_span,
+        version=get_package_version(),
+        description=SERVER_DESCRIPTION,
+        instructions=SERVER_INSTRUCTIONS,
+    )
+
+    register_tools(server)
+    register_resources(server)
+    register_prompts(server)
+
+    return server

{source_context_mcp-0.1.dev3 → source_context_mcp-0.1.dev5}/src/source_context_mcp/tools/__init__.py

@@ -8,7 +8,7 @@ from .vector import register_tools as register_vector_tools
 
 def register_tools(mcp: MCPServer) -> None:
     """
-    Registry tools for MCPServer.
+    Register tools for MCPServer.
     Args:
         mcp: instance of MCPServer
     """
@@ -17,3 +17,6 @@ def register_tools(mcp: MCPServer) -> None:
     register_base_tools(mcp)
     register_graph_tools(mcp)
     register_vector_tools(mcp)
+
+
+__all__ = ["register_tools"]

{source_context_mcp-0.1.dev3 → source_context_mcp-0.1.dev5}/src/source_context_mcp/tools/base.py

@@ -1,34 +1,24 @@
-from typing import Any
+from typing import Annotated, Any
 
 from mcp.server import MCPServer
 from mcp.server.mcpserver import Context
+from pydantic import Field
 
 from source_context_mcp.core import ApiClientDep, AppContext
 
 
 def register_tools(mcp: MCPServer) -> None:
-    """
-    Register bases tools:
-        - list user's available workspaces
-        - list repos in workspace
-        - list branches in repo
-        - list projects in branch
 
-    Args:
-        mcp: MCPServer instance
-    """
-
-    @mcp.tool(description="List all available workspaces that current user can access")
+    @mcp.tool(description="List all workspaces accessible to the current user.")
     async def list_workspaces(client: ApiClientDep) -> Any:
         res = await client.get("/general/workspaces", response_model=list)
         return res.result()
 
-    @mcp.tool(
-        description=(
-            "Get the default settings for specified directory.Include default workspace id adn default repository id."
-        )
-    )
-    async def get_path_settings(ctx: Context[AppContext], path: str) -> dict[str, Any]:
+    @mcp.tool(description="Get default workspace and repository settings configured for a local path.")
+    async def get_path_settings(
+        ctx: Context[AppContext],
+        path: Annotated[str, Field(description="Local directory path to look up default settings for.")],
+    ) -> dict[str, Any]:
         app_context: AppContext = ctx.request_context.lifespan_context
         settings = app_context.settings
         return {
@@ -38,25 +28,27 @@ def register_tools(mcp: MCPServer) -> None:
         }
 
     @mcp.tool(
-        description=(
-            "Get default workspace. "
-            "This is the default workspace use settings in case current path has no default config"
-        )
+        description="Get the server-configured default workspace ID, used when the current path has no path-specific "
+        "default."
     )
     async def default_workspace(ctx: Context[AppContext]) -> Any:
         app_context: AppContext = ctx.request_context.lifespan_context
         return app_context.settings.DEFAULT_WORKSPACE_ID
 
-    @mcp.tool(description="List all available repositories in workspace")
+    @mcp.tool(description="List all repositories in a workspace.")
     async def list_repositories(
         client: ApiClientDep,
-        workspace_id: int,
+        workspace_id: Annotated[int, Field(description="Workspace ID.", ge=1)],
     ) -> Any:
         res = await client.post("/general/repositories", {"workspace_id": workspace_id})
         return res.result()
 
-    @mcp.tool(description="List all available branches in specified repository.")
-    async def list_branches(client: ApiClientDep, workspace_id: int, repository_id: int) -> Any:
+    @mcp.tool(description="List all branches in a repository.")
+    async def list_branches(
+        client: ApiClientDep,
+        workspace_id: Annotated[int, Field(description="Workspace ID.", ge=1)],
+        repository_id: Annotated[int, Field(description="Repository ID.", ge=1)],
+    ) -> Any:
         req_body = {
             "workspace_id": workspace_id,
             "repository_id": repository_id,
@@ -64,8 +56,13 @@ def register_tools(mcp: MCPServer) -> None:
         res = await client.post("/general/branches", req_body)
         return res.result()
 
-    @mcp.tool(description="List all available projects in specific branch.")
-    async def list_projects(client: ApiClientDep, workspace_id: int, repository_id: int, branch_name: str) -> Any:
+    @mcp.tool(description="List all projects on a branch.")
+    async def list_projects(
+        client: ApiClientDep,
+        workspace_id: Annotated[int, Field(description="Workspace ID.", ge=1)],
+        repository_id: Annotated[int, Field(description="Repository ID.", ge=1)],
+        branch_name: Annotated[str, Field(description="Branch name.")],
+    ) -> Any:
         req_body = {
             "workspace_id": workspace_id,
             "repo_id": repository_id,

source_context_mcp-0.1.dev5/src/source_context_mcp/tools/debug.py

@@ -0,0 +1,27 @@
+from mcp.server import MCPServer
+from mcp.server.mcpserver import Context
+
+from source_context_mcp.core import AppContext, Settings
+from source_context_mcp.core.metadata import get_package_version
+
+
+def register_tools(mcp: MCPServer):
+    """
+     Register development-only MCP tools.
+
+    These tools are registered only when the package version is a
+    development release (e.g. ``0.1.0.dev1``). They are excluded from
+    alpha, beta, release candidate, and stable builds.
+
+    Args:
+        mcp: The MCP server instance to register tools with.
+    """
+
+    version = get_package_version()
+    if "dev" not in version:
+        return
+
+    @mcp.tool(description="Show current server configuration. For development use only.")
+    def debug(ctx: Context[AppContext]) -> Settings:
+        app_context: AppContext = ctx.request_context.lifespan_context
+        return app_context.settings

source_context_mcp-0.1.dev5/src/source_context_mcp/tools/graph.py

@@ -0,0 +1,76 @@
+from typing import Annotated, Any, Literal
+
+from mcp.server import MCPServer
+from pydantic import Field
+
+from source_context_mcp.core import ApiClientDep
+
+
+def register_tools(mcp: MCPServer) -> None:
+
+    @mcp.tool(description="List all files in a project.")
+    async def list_files_in_project(
+        client: ApiClientDep,
+        project_id: Annotated[str, Field(description="Project ID.")],
+    ) -> Any:
+        res = await client.get(f"/graph/projects/{project_id}/files")
+        return res.result()
+
+    @mcp.tool(description="Get file structure: classes and methods.")
+    async def get_file_structure(
+        client: ApiClientDep,
+        file_id: Annotated[str, Field(description="File ID.")],
+    ) -> Any:
+        res = await client.get(f"/graph/files/{file_id}/structure")
+        return res.result()
+
+    @mcp.tool(description="Read file content.")
+    async def get_file_content(
+        client: ApiClientDep,
+        file_id: Annotated[str, Field(description="File ID.")],
+    ) -> Any:
+        res = await client.get(f"/graph/files/{file_id}/content")
+        return res.result()
+
+    @mcp.tool(description="Get node metadata: id, name, file_id, position in file.")
+    async def get_node_info(
+        client: ApiClientDep,
+        node_id: Annotated[str, Field(description="Node ID.")],
+    ) -> Any:
+        res = await client.get(f"/graph/nodes/{node_id}")
+        return res.result()
+
+    @mcp.tool(description="Get node source content.")
+    async def get_node_content(
+        client: ApiClientDep,
+        node_id: Annotated[str, Field(description="Node ID.")],
+    ) -> Any:
+        res = await client.get(f"/graph/nodes/{node_id}/content")
+        return res.result()
+
+    # @mcp.tool(description="This tool not implemented yet.")
+    # async def find_node_by_name(
+    #     client: ApiClientDep,
+    #     name: Annotated[str, Field(description="The name of the node")],
+    #     node_type: Annotated[
+    #         Literal["type-definition", "", None],
+    #         Field(default=None, description="The type of the node. Default is all types"),
+    #     ],
+    # ) -> Any:
+    #     return []
+
+    @mcp.tool(description="Find all nodes that call or reference the specified node.")
+    async def find_node_usages(
+        client: ApiClientDep,
+        node_id: Annotated[str, Field(description="Node ID.")],
+    ) -> Any:
+        res = await client.get(f"/graph/nodes/{node_id}/usages")
+        return res.result()
+
+    @mcp.tool(description="Find all nodes that the specified node calls or references.")
+    async def find_node_callees(
+        client: ApiClientDep,
+        node_id: Annotated[str, Field(description="Node ID.")],
+    ) -> Any:
+        res = await client.get(f"/graph/nodes/{node_id}/callees")
+        return res.result()

source_context_mcp-0.1.dev5/src/source_context_mcp/tools/vector.py

@@ -0,0 +1,42 @@
+from typing import Annotated, Any
+
+from mcp.server import MCPServer
+from pydantic import Field
+
+from source_context_mcp.core import ApiClientDep
+
+
+def register_tools(mcp: MCPServer) -> None:
+
+    @mcp.tool(description="Semantic search across all repositories and branches in a workspace.")
+    async def search_in_workspace(
+        client: ApiClientDep,
+        query: Annotated[str, Field(description="Query to search in workspace.")],
+        workspace_id: Annotated[int, Field(ge=1, description="Workspace ID.")],
+        top_k: Annotated[int, Field(default=5, ge=1, le=50, description="Number of top results to return.")],
+    ) -> Any:
+        req_body = {
+            "query": query,
+            "top_k": top_k,
+        }
+
+        res = await client.post(f"/vector/search/{workspace_id}", req_body)
+
+        return res.result()
+
+    @mcp.tool(description="Semantic search scoped to a specific repository and branch.")
+    async def search_in_repo_and_branch(
+        client: ApiClientDep,
+        repository_id: Annotated[int, Field(ge=1, description="Repository ID.")],
+        branch_name: Annotated[str, Field(description="Branch name.")],
+        query: Annotated[str, Field(description="Query to search in branch scope.")],
+        top_k: Annotated[int, Field(default=5, ge=1, le=50, description="Number of top results to return.")],
+    ) -> Any:
+        req_body = {
+            "query": query,
+            "top_k": top_k,
+        }
+
+        res = await client.post(f"/vector/search/{repository_id}/{branch_name}", req_body)
+
+        return res.result()

source_context_mcp-0.1.dev3/PKG-INFO

@@ -1,17 +0,0 @@
-Metadata-Version: 2.3
-Name: source-context-mcp
-Version: 0.1.dev3
-Summary: Local Model Context Protocol (MCP) server for Source Context code intelligence.
-Author: Le Ngoc Tu, Dang Huu Hieu, Huynh Phat Tai
-Author-email: Le Ngoc Tu <tuleaibk@gmail.com>, Dang Huu Hieu <danghuuhieu038@gmail.com>, Huynh Phat Tai <huynhphtai@gmail.com>
-Requires-Dist: httpx>=0.28.1
-Requires-Dist: mcp[cli]>=2.0.0
-Requires-Dist: pydantic>=2.13.4
-Requires-Dist: pydantic-settings>=2.14.2
-Requires-Dist: tomli-w>=1.2.0
-Requires-Dist: typer>=0.27.0
-Requires-Python: >=3.12
-Project-URL: Repository, https://github.com/TuLe142857/source-context
-Description-Content-Type: text/markdown
-
-# Readme for MCP Server

source_context_mcp-0.1.dev3/README.md

@@ -1 +0,0 @@
-# Readme for MCP Server

source_context_mcp-0.1.dev3/src/source_context_mcp/server.py

@@ -1,48 +0,0 @@
-from collections.abc import AsyncIterator
-from contextlib import asynccontextmanager
-
-from mcp.server import MCPServer
-
-from source_context_mcp.core import ApiClient, AppContext, get_settings_with_overrides
-from source_context_mcp.tools import register_tools
-
-
-def make_life_span(
-    base_url_override: str | None = None, pat_override: str | None = None, workspace_id_override: int | None = None
-):
-    @asynccontextmanager
-    async def server_lifespan(app: MCPServer) -> AsyncIterator[AppContext]:
-        settings = get_settings_with_overrides(
-            server_url_override=base_url_override,
-            pat_override=pat_override,
-            default_workspace_id_override=workspace_id_override,
-        )
-
-        yield AppContext(
-            api_client=ApiClient(base_url=settings.SERVER_URL, token=settings.PAT.get_secret_value()), settings=settings
-        )
-
-    return server_lifespan
-
-
-def create_server(
-    base_url_override: str | None = None, pat_override: str | None = None, workspace_id_override: int | None = None
-) -> MCPServer:
-    """
-    Create an MCPServer instance.
-    Returns:
-        MCPServer instance.
-    """
-
-    life_span = make_life_span(
-        base_url_override=base_url_override, pat_override=pat_override, workspace_id_override=workspace_id_override
-    )
-
-    server = MCPServer(
-        name="SourceContextMCP",
-        lifespan=life_span,
-    )
-
-    register_tools(server)
-
-    return server

source_context_mcp-0.1.dev3/src/source_context_mcp/tools/debug.py

@@ -1,11 +0,0 @@
-from mcp.server import MCPServer
-from mcp.server.mcpserver import Context
-
-from source_context_mcp.core import AppContext, Settings
-
-
-def register_tools(mcp: MCPServer):
-    @mcp.tool(description="This tool for development env only. Show all current config. Read source code to see more")
-    def debug(ctx: Context[AppContext]) -> Settings:
-        app_context: AppContext = ctx.request_context.lifespan_context
-        return app_context.settings

source_context_mcp-0.1.dev3/src/source_context_mcp/tools/graph.py

@@ -1,48 +0,0 @@
-from typing import Any
-
-from mcp.server import MCPServer
-
-from source_context_mcp.core import ApiClientDep
-
-
-def register_tools(mcp: MCPServer) -> None:
-    """
-    Registers all the graph tools.
-    Args:
-        mcp: MCPServer instance
-    """
-
-    @mcp.tool(description="List all files in specified project.")
-    async def list_files_in_project(client: ApiClientDep, project_id: str) -> Any:
-        res = await client.get(f"/graph/projects/{project_id}/files")
-        return res.result()
-
-    @mcp.tool(description="Inspect file structure(classes and methods")
-    async def get_file_structure(client: ApiClientDep, file_id: str) -> Any:
-        res = await client.get(f"/graph/files/{file_id}/structure")
-        return res.result()
-
-    @mcp.tool(description="Read file content.")
-    async def get_file_content(client: ApiClientDep, file_id: str) -> Any:
-        res = await client.get(f"/graph/files/{file_id}/content")
-        return res.result()
-
-    @mcp.tool(description="Get node information: id, name, file_id, position in file")
-    async def get_node_info(client: ApiClientDep, node_id: str) -> Any:
-        res = await client.get(f"/graph/nodes/{node_id}")
-        return res.result()
-
-    @mcp.tool(description="Get node information.")
-    async def get_node_content(client: ApiClientDep, node_id: str) -> Any:
-        res = await client.get(f"/graph/nodes/{node_id}/content")
-        return res.result()
-
-    @mcp.tool(description="Find all nodes that call/reference to the specified node.")
-    async def find_node_usages(client: ApiClientDep, node_id: str) -> Any:
-        res = await client.get(f"/graph/nodes/{node_id}/usages")
-        return res.result()
-
-    @mcp.tool(description="Find all nodes(or its children) that the specified node is calling or reference to.")
-    async def find_node_callees(client: ApiClientDep, node_id: str) -> Any:
-        res = await client.get(f"/graph/nodes/{node_id}/callees")
-        return res.result()

source_context_mcp-0.1.dev3/src/source_context_mcp/tools/vector.py

@@ -1,37 +0,0 @@
-from typing import Any
-
-from mcp.server import MCPServer
-
-from source_context_mcp.core import ApiClientDep
-
-
-def register_tools(mcp: MCPServer) -> None:
-    """
-    Registers all the vector tools.
-    Args:
-        mcp: MCP server instance
-    """
-
-    @mcp.tool(description="Sematic search.")
-    async def search_in_workspace(client: ApiClientDep, query: str, workspace_id: int, top_k: int = 5) -> Any:
-        req_body = {
-            "query": query,
-            "top_k": top_k,
-        }
-
-        res = await client.post(f"/vector/search/{workspace_id}", req_body)
-
-        return res.result()
-
-    @mcp.tool(description="Sematic search.")
-    async def search_in_repo_and_branch(
-        client: ApiClientDep, repository_id: int, branch_name: str, query: str, top_k: int = 5
-    ) -> Any:
-        req_body = {
-            "query": query,
-            "top_k": top_k,
-        }
-
-        res = await client.post(f"/vector/search/{repository_id}/{branch_name}", req_body)
-
-        return res.result()