codesurface 0.1.0__tar.gz

codesurface-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,26 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: Install build tools
+        run: pip install build
+
+      - name: Build wheel and sdist
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

codesurface-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+.venv/
+venv/
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+uv.lock
+.env
+.idea

codesurface-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Codeturion
+
+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.

codesurface-0.1.0/PKG-INFO

@@ -0,0 +1,196 @@
+Metadata-Version: 2.4
+Name: codesurface
+Version: 0.1.0
+Summary: MCP server that indexes a C# codebase's public API at startup and serves it via compact tool responses — saving tokens vs reading source files
+Project-URL: Homepage, https://github.com/Codeturion/codesurface
+Project-URL: Repository, https://github.com/Codeturion/codesurface
+Project-URL: Issues, https://github.com/Codeturion/codesurface/issues
+Author-email: Codeturion <fuatcankoseoglu@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2026 Codeturion
+        
+        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.
+License-File: LICENSE
+Keywords: api,code-intelligence,csharp,dotnet,index,mcp,unity
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Requires-Dist: mcp[cli]>=1.8.0
+Description-Content-Type: text/markdown
+
+# codesurface
+
+[![PyPI Version](https://img.shields.io/pypi/v/codesurface.svg)](https://pypi.org/project/codesurface/)
+[![PyPI Downloads](https://img.shields.io/pypi/dm/codesurface.svg)](https://pypi.org/project/codesurface/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+
+**MCP server that indexes a C# codebase's public API at startup and serves it via compact tool responses — saving tokens vs reading source files.**
+
+Parses all `.cs` files, extracts public classes/methods/properties/fields/events, and serves them through 5 MCP tools. Works with Claude Code, Cursor, Windsurf, or any MCP-compatible AI tool.
+
+## Quick Start
+
+```bash
+pip install codesurface
+```
+
+Then add to your `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "codesurface": {
+      "command": "codesurface",
+      "args": ["--project", "/path/to/your/src"]
+    }
+  }
+}
+```
+
+Point `--project` at any directory containing `.cs` files — a Unity `Assets/Scripts` folder, a .NET `src/` tree, a Godot C# project, etc.
+
+Restart your AI tool and ask: *"What methods does MyService have?"*
+
+## Tools
+
+| Tool | Purpose | Example |
+|------|---------|---------|
+| `search` | Find APIs by keyword | "MergeService", "BlastBoard", "GridCoord" |
+| `get_signature` | Exact signature by name or FQN | "TryMerge", "CampGame.Services.IMergeService.TryMerge" |
+| `get_class` | Full class reference card — all public members | "BlastBoardModel" → all methods/fields/properties |
+| `get_stats` | Overview of indexed codebase | File count, record counts, namespace breakdown |
+| `reindex` | Incremental index update (mtime-based) | Only re-parses changed/new/deleted files |
+
+## Benchmarks
+
+Measured against a real Unity game project (129 files, 1,018 API records) across a 10-step cross-cutting research workflow.
+
+| Strategy | Total Tokens | vs MCP |
+|----------|-------------|--------|
+| **MCP (codesurface)** | **1,021** | — |
+| Skilled Agent (Grep + partial Read) | 4,453 | 4.4x more |
+| Naive Agent (Grep + full Read) | 11,825 | 11.6x more |
+
+Even with follow-up reads for implementation detail, the hybrid MCP + targeted Read approach uses **54% fewer tokens** than a skilled Grep+Read agent.
+
+See [workflow-benchmark.md](workflow-benchmark.md) for the full step-by-step analysis.
+
+## Setup Details
+
+<details>
+<summary>Claude Code configuration</summary>
+
+Add to `<project>/.mcp.json`:
+
+**Using uv (recommended):**
+```json
+{
+  "mcpServers": {
+    "codesurface": {
+      "command": "uv",
+      "args": ["run", "--directory", "/path/to/codesurface", "codesurface", "--project", "/path/to/your/src"]
+    }
+  }
+}
+```
+
+**Using pip install:**
+```json
+{
+  "mcpServers": {
+    "codesurface": {
+      "command": "codesurface",
+      "args": ["--project", "/path/to/your/src"]
+    }
+  }
+}
+```
+
+</details>
+
+<details>
+<summary>CLAUDE.md snippet (recommended)</summary>
+
+Add to your project's `CLAUDE.md` so the AI knows when to use the tools:
+
+```markdown
+## Codebase API Lookup (codesurface MCP)
+
+Use the `codesurface` MCP tools to look up your project's classes, methods, properties, and fields instead of reading source files.
+
+| When | Tool | Example |
+|------|------|---------|
+| Searching for an API by keyword | `search` | `search("MergeService")` |
+| Need exact method signature | `get_signature` | `get_signature("TryMerge")` |
+| Want all members on a class | `get_class` | `get_class("BlastBoardModel")` |
+| Overview of indexed codebase | `get_stats` | `get_stats()` |
+| After creating/deleting C# files | `reindex` | `reindex()` |
+```
+
+</details>
+
+<details>
+<summary>Project structure</summary>
+
+```
+codesurface/
+├── src/codesurface/
+│   ├── server.py        # MCP server — 5 tools
+│   ├── db.py            # SQLite + FTS5 database layer
+│   └── cs_parser.py     # C# public API parser
+├── pyproject.toml
+└── README.md
+```
+
+</details>
+
+<details>
+<summary>Troubleshooting</summary>
+
+**"No codebase indexed"**
+- Ensure `--project` points to a directory containing `.cs` files
+- The server indexes at startup — check stderr for the "Indexed N records" message
+
+**Server won't start**
+- Check Python version: `python --version` (needs 3.10+)
+- Check `mcp[cli]` is installed: `pip install mcp[cli]`
+
+**Stale results after editing C# files**
+- Call `reindex()` — only re-parses files whose modification time changed, fast even on large codebases
+
+</details>
+
+---
+
+## Contact
+
+fuatcankoseoglu@gmail.com
+
+## License
+
+MIT

codesurface-0.1.0/README.md

@@ -0,0 +1,152 @@
+# codesurface
+
+[![PyPI Version](https://img.shields.io/pypi/v/codesurface.svg)](https://pypi.org/project/codesurface/)
+[![PyPI Downloads](https://img.shields.io/pypi/dm/codesurface.svg)](https://pypi.org/project/codesurface/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+
+**MCP server that indexes a C# codebase's public API at startup and serves it via compact tool responses — saving tokens vs reading source files.**
+
+Parses all `.cs` files, extracts public classes/methods/properties/fields/events, and serves them through 5 MCP tools. Works with Claude Code, Cursor, Windsurf, or any MCP-compatible AI tool.
+
+## Quick Start
+
+```bash
+pip install codesurface
+```
+
+Then add to your `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "codesurface": {
+      "command": "codesurface",
+      "args": ["--project", "/path/to/your/src"]
+    }
+  }
+}
+```
+
+Point `--project` at any directory containing `.cs` files — a Unity `Assets/Scripts` folder, a .NET `src/` tree, a Godot C# project, etc.
+
+Restart your AI tool and ask: *"What methods does MyService have?"*
+
+## Tools
+
+| Tool | Purpose | Example |
+|------|---------|---------|
+| `search` | Find APIs by keyword | "MergeService", "BlastBoard", "GridCoord" |
+| `get_signature` | Exact signature by name or FQN | "TryMerge", "CampGame.Services.IMergeService.TryMerge" |
+| `get_class` | Full class reference card — all public members | "BlastBoardModel" → all methods/fields/properties |
+| `get_stats` | Overview of indexed codebase | File count, record counts, namespace breakdown |
+| `reindex` | Incremental index update (mtime-based) | Only re-parses changed/new/deleted files |
+
+## Benchmarks
+
+Measured against a real Unity game project (129 files, 1,018 API records) across a 10-step cross-cutting research workflow.
+
+| Strategy | Total Tokens | vs MCP |
+|----------|-------------|--------|
+| **MCP (codesurface)** | **1,021** | — |
+| Skilled Agent (Grep + partial Read) | 4,453 | 4.4x more |
+| Naive Agent (Grep + full Read) | 11,825 | 11.6x more |
+
+Even with follow-up reads for implementation detail, the hybrid MCP + targeted Read approach uses **54% fewer tokens** than a skilled Grep+Read agent.
+
+See [workflow-benchmark.md](workflow-benchmark.md) for the full step-by-step analysis.
+
+## Setup Details
+
+<details>
+<summary>Claude Code configuration</summary>
+
+Add to `<project>/.mcp.json`:
+
+**Using uv (recommended):**
+```json
+{
+  "mcpServers": {
+    "codesurface": {
+      "command": "uv",
+      "args": ["run", "--directory", "/path/to/codesurface", "codesurface", "--project", "/path/to/your/src"]
+    }
+  }
+}
+```
+
+**Using pip install:**
+```json
+{
+  "mcpServers": {
+    "codesurface": {
+      "command": "codesurface",
+      "args": ["--project", "/path/to/your/src"]
+    }
+  }
+}
+```
+
+</details>
+
+<details>
+<summary>CLAUDE.md snippet (recommended)</summary>
+
+Add to your project's `CLAUDE.md` so the AI knows when to use the tools:
+
+```markdown
+## Codebase API Lookup (codesurface MCP)
+
+Use the `codesurface` MCP tools to look up your project's classes, methods, properties, and fields instead of reading source files.
+
+| When | Tool | Example |
+|------|------|---------|
+| Searching for an API by keyword | `search` | `search("MergeService")` |
+| Need exact method signature | `get_signature` | `get_signature("TryMerge")` |
+| Want all members on a class | `get_class` | `get_class("BlastBoardModel")` |
+| Overview of indexed codebase | `get_stats` | `get_stats()` |
+| After creating/deleting C# files | `reindex` | `reindex()` |
+```
+
+</details>
+
+<details>
+<summary>Project structure</summary>
+
+```
+codesurface/
+├── src/codesurface/
+│   ├── server.py        # MCP server — 5 tools
+│   ├── db.py            # SQLite + FTS5 database layer
+│   └── cs_parser.py     # C# public API parser
+├── pyproject.toml
+└── README.md
+```
+
+</details>
+
+<details>
+<summary>Troubleshooting</summary>
+
+**"No codebase indexed"**
+- Ensure `--project` points to a directory containing `.cs` files
+- The server indexes at startup — check stderr for the "Indexed N records" message
+
+**Server won't start**
+- Check Python version: `python --version` (needs 3.10+)
+- Check `mcp[cli]` is installed: `pip install mcp[cli]`
+
+**Stale results after editing C# files**
+- Call `reindex()` — only re-parses files whose modification time changed, fast even on large codebases
+
+</details>
+
+---
+
+## Contact
+
+fuatcankoseoglu@gmail.com
+
+## License
+
+MIT

codesurface-0.1.0/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "codesurface"
+version = "0.1.0"
+description = "MCP server that indexes a C# codebase's public API at startup and serves it via compact tool responses — saving tokens vs reading source files"
+readme = "README.md"
+license = {file = "LICENSE"}
+requires-python = ">=3.10"
+authors = [
+    {name = "Codeturion", email = "fuatcankoseoglu@gmail.com"},
+]
+keywords = ["mcp", "csharp", "api", "index", "code-intelligence", "unity", "dotnet"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries",
+]
+dependencies = [
+    "mcp[cli]>=1.8.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/Codeturion/codesurface"
+Repository = "https://github.com/Codeturion/codesurface"
+Issues = "https://github.com/Codeturion/codesurface/issues"
+
+[project.scripts]
+codesurface = "codesurface.server:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/codesurface"]