authful-mcp-proxy 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Potentially problematic release.


This version of authful-mcp-proxy might be problematic. Click here for more details.

@@ -0,0 +1,646 @@
1
+ Metadata-Version: 2.4
2
+ Name: authful-mcp-proxy
3
+ Version: 0.1.0
4
+ Summary: A Model Context Protocol (MCP) proxy server that performs OIDC authentication to obtain access tokens for remote MCP servers protected by token validation, and bridges HTTP transport to local stdio for MCP clients like Claude Desktop.
5
+ Author-email: Stephan Eberle <stephaneberle9@gmail.com>
6
+ License-File: LICENSE
7
+ Requires-Python: >=3.10
8
+ Requires-Dist: fastmcp>=2.12.4
9
+ Description-Content-Type: text/markdown
10
+
11
+ <!-- omit from toc -->
12
+ Authful MCP Proxy
13
+ =================
14
+
15
+ A [Model Context Protocol](https://modelcontextprotocol.com) (MCP) proxy server that performs OIDC authentication to obtain access tokens for remote MCP servers protected by token validation, and bridges HTTP transport to local stdio for MCP clients like Claude Desktop.
16
+
17
+ - [What Is This For?](#what-is-this-for)
18
+ - [Technical Background](#technical-background)
19
+ - [Usage](#usage)
20
+ - [Quick Start](#quick-start)
21
+ - [First Run](#first-run)
22
+ - [Configuration Options](#configuration-options)
23
+ - [Required Configuration](#required-configuration)
24
+ - [Optional Configuration](#optional-configuration)
25
+ - [Advanced Options](#advanced-options)
26
+ - [Usage Examples](#usage-examples)
27
+ - [Example 1: Claude Desktop (Recommended)](#example-1-claude-desktop-recommended)
28
+ - [Example 2: Using Latest Version](#example-2-using-latest-version)
29
+ - [Example 3: With Client Secret (Confidential Client)](#example-3-with-client-secret-confidential-client)
30
+ - [Example 4: Custom Redirect Port](#example-4-custom-redirect-port)
31
+ - [Example 5: Development from Source](#example-5-development-from-source)
32
+ - [Example 6: Debug Mode](#example-6-debug-mode)
33
+ - [Using with Other MCP Clients](#using-with-other-mcp-clients)
34
+ - [MCP Inspector](#mcp-inspector)
35
+ - [Cursor / Windsurf](#cursor--windsurf)
36
+ - [Command Line / Direct Usage](#command-line--direct-usage)
37
+ - [Credential Management](#credential-management)
38
+ - [Where Are Credentials Stored?](#where-are-credentials-stored)
39
+ - [Clear Cached Credentials](#clear-cached-credentials)
40
+ - [Troubleshooting](#troubleshooting)
41
+ - [Browser Doesn't Open for Authentication](#browser-doesnt-open-for-authentication)
42
+ - [401 Unauthorized Errors](#401-unauthorized-errors)
43
+ - [Redirect URI Mismatch](#redirect-uri-mismatch)
44
+ - [Token Refresh Failures](#token-refresh-failures)
45
+ - [Connection to Backend Fails](#connection-to-backend-fails)
46
+ - [MCP Client Doesn't Recognize the Proxy](#mcp-client-doesnt-recognize-the-proxy)
47
+ - [Debug Logging](#debug-logging)
48
+ - [Still Having Issues?](#still-having-issues)
49
+ - [Development](#development)
50
+ - [Setup](#setup)
51
+ - [Run](#run)
52
+ - [Inside Dev Environment](#inside-dev-environment)
53
+ - [Outside Dev Environment](#outside-dev-environment)
54
+ - [With MCP Inspector](#with-mcp-inspector)
55
+ - [With Minimal Token-Validating MCP Backend Example](#with-minimal-token-validating-mcp-backend-example)
56
+ - [Check](#check)
57
+ - [Enable Automatic Execution on Git Commit](#enable-automatic-execution-on-git-commit)
58
+ - [Manual Execution](#manual-execution)
59
+ - [Test](#test)
60
+ - [Package](#package)
61
+
62
+ # What Is This For?
63
+
64
+ Use `authful-mcp-proxy` when you need to connect your MCP client (like Claude Desktop, Cursor, or Windsurf) to a remote MCP server that:
65
+ - Is protected by OAuth/OIDC token validation
66
+ - Doesn't handle authentication itself (no built-in OAuth flows)
67
+ - Returns `401 Unauthorized` without proper access tokens
68
+
69
+ The proxy handles the full OIDC authentication flow, securely stores your credentials in `~/.fastmcp/oauth-mcp-client-cache/`, and automatically refreshes tokens as needed.
70
+
71
+ ## Technical Background
72
+
73
+ Typically, securing MCP connections with OAuth or OpenID connect (OIDC) requires "authful" MCP servers that [coordinate with external identity providers](https://gofastmcp.com/servers/auth/authentication#external-identity-providers). MCP clients handle authentication through the MCP server, which in turn interacts with the OAuth or OIDC authorization server. However, this doesn't work with MCP servers only protected by [token validation](https://gofastmcp.com/servers/auth/authentication#token-validation), i.e., MCP servers that trust tokens from a known issuer but don't coordinate with the OAuth/OIDC authorization server themselves. In such scenarios, MCP clients detect the MCP server isn't authful and skip the OAuth/OIDC authentication entirely, resulting in `401 Unauthorized` errors for all tool, resource, and prompt requests.
74
+
75
+ This MCP proxy fills that gap by handling authentication independently through direct OIDC authorization server interaction. It performs the OAuth authorization code flow by opening the user's browser to the OIDC authorization endpoint for login and scope approval. A temporary local HTTP server receives the OAuth redirect and exchanges the authorization code for access and refresh tokens using PKCE. The access token is used as a Bearer token for all backend MCP server requests and cached locally to avoid repeated browser interactions. When tokens expire, the proxy automatically obtains new ones using the refresh token.
76
+
77
+ # Usage
78
+
79
+ ## Quick Start
80
+
81
+ The simplest way to use `authful-mcp-proxy` with MCP clients like Claude Desktop:
82
+
83
+ ```jsonc
84
+ {
85
+ "mcpServers": {
86
+ "my-protected-server": {
87
+ "command": "uvx",
88
+ "args": [
89
+ "authful-mcp-proxy",
90
+ "https://mcp-backend.company.com/mcp"
91
+ ],
92
+ "env": {
93
+ "OIDC_ISSUER_URL": "https://auth.company.com",
94
+ "OIDC_CLIENT_ID": "your-client-id"
95
+ }
96
+ }
97
+ }
98
+ }
99
+ ```
100
+
101
+ > ℹ️ **Note:** Only two really essential OIDC parameters (issuer URL and client ID) must be specified. Other OIDC parameters (scopes, redirect URL, etc.) use defaults that can be found in the [Configuration Options](#configuration-options) section below.
102
+
103
+ > ⚠️ **Important:** Make sure your OIDC client is configured with `http://localhost:8080/auth/callback` as an allowed redirect URI!
104
+
105
+ ### First Run
106
+
107
+ The proxy will open your browser for authentication. After you log in and approve the required scopes, your credentials are cached locally and you won't need to authenticate again until tokens expire.
108
+
109
+ ## Configuration Options
110
+
111
+ All options can be set via environment variables in the `env` block or passed as CLI arguments (see `uvx authful-mcp-proxy --help`).
112
+
113
+ ### Required Configuration
114
+
115
+ | Environment Variable | Description | Example |
116
+ |---------------------|-------------|---------|
117
+ | `MCP_BACKEND_URL` | Remote MCP server URL (can also be first argument) | `https://mcp.example.com/mcp` |
118
+ | `OIDC_ISSUER_URL` | Your OIDC provider's issuer URL | `https://auth.example.com` |
119
+ | `OIDC_CLIENT_ID` | OAuth client ID from your OIDC provider | `my-app-client-id` |
120
+
121
+ ### Optional Configuration
122
+
123
+ | Environment Variable | Default | Description |
124
+ |---------------------|---------|-------------|
125
+ | `OIDC_CLIENT_SECRET` | _(none)_ | Client secret (not needed for public clients that don't require any such) |
126
+ | `OIDC_SCOPES` | `openid profile email` | Space-separated OAuth scopes |
127
+ | `OIDC_REDIRECT_URL` | `http://localhost:8080/auth/callback` | OAuth callback URL |
128
+
129
+ ### Advanced Options
130
+
131
+ | CLI Flag | Description |
132
+ |----------|-------------|
133
+ | `--no-banner` | Suppress the startup banner |
134
+ | `--silent` | Show only error messages |
135
+ | `--debug` | Enable detailed debug logging |
136
+
137
+ ## Usage Examples
138
+
139
+ ### Example 1: Claude Desktop (Recommended)
140
+
141
+ Add to your Claude Desktop config (accessible via Settings → Developer → Edit Config):
142
+
143
+ ```jsonc
144
+ {
145
+ "mcpServers": {
146
+ "company-tools": {
147
+ "command": "uvx",
148
+ "args": [
149
+ "authful-mcp-proxy",
150
+ "https://mcp-backend.company.com/mcp"
151
+ ],
152
+ "env": {
153
+ "OIDC_ISSUER_URL": "https://auth.company.com",
154
+ "OIDC_CLIENT_ID": "claude-desktop-client",
155
+ "OIDC_SCOPES": "openid profile mcp:read mcp:write"
156
+ }
157
+ }
158
+ }
159
+ }
160
+ ```
161
+
162
+ > ⚠️ **Important:** Make sure your OIDC client is configured with `http://localhost:8080/auth/callback` as an allowed redirect URI!
163
+
164
+ Restart Claude Desktop to apply changes.
165
+
166
+ ### Example 2: Using Latest Version
167
+
168
+ To always use the latest version from PyPI (auto-updates):
169
+
170
+ ```jsonc
171
+ {
172
+ "mcpServers": {
173
+ "my-server": {
174
+ "command": "uvx",
175
+ "args": [
176
+ "authful-mcp-proxy@latest",
177
+ "https://mcp.example.com/mcp"
178
+ ],
179
+ "env": {
180
+ "OIDC_ISSUER_URL": "https://auth.example.com",
181
+ "OIDC_CLIENT_ID": "my-client-id"
182
+ }
183
+ }
184
+ }
185
+ }
186
+ ```
187
+
188
+ > ⚠️ **Important:** Make sure your OIDC client is configured with `http://localhost:8080/auth/callback` as an allowed redirect URI!
189
+
190
+ ### Example 3: With Client Secret (Confidential Client)
191
+
192
+ For OIDC confidential clients requiring a secret:
193
+
194
+ ```jsonc
195
+ {
196
+ "mcpServers": {
197
+ "secure-server": {
198
+ "command": "uvx",
199
+ "args": ["authful-mcp-proxy", "https://api.example.com/mcp"],
200
+ "env": {
201
+ "OIDC_ISSUER_URL": "https://login.example.com",
202
+ "OIDC_CLIENT_ID": "your-confidential-client-id",
203
+ "OIDC_CLIENT_SECRET": "your-client-secret",
204
+ "OIDC_SCOPES": "openid profile email api:access"
205
+ }
206
+ }
207
+ }
208
+ }
209
+ ```
210
+
211
+ > ⚠️ **Important:** Make sure your OIDC client is configured with `http://localhost:8080/auth/callback` as an allowed redirect URI!
212
+
213
+ ### Example 4: Custom Redirect Port
214
+
215
+ If port 8080 is already in use, specify a different port:
216
+
217
+ ```jsonc
218
+ {
219
+ "mcpServers": {
220
+ "my-server": {
221
+ "command": "uvx",
222
+ "args": ["authful-mcp-proxy", "https://mcp.example.com"],
223
+ "env": {
224
+ "OIDC_ISSUER_URL": "https://auth.example.com",
225
+ "OIDC_CLIENT_ID": "my-client-id",
226
+ "OIDC_REDIRECT_URL": "http://localhost:9090/auth/callback"
227
+ }
228
+ }
229
+ }
230
+ }
231
+ ```
232
+
233
+ > ⚠️ **Important:** Make sure your OIDC client is configured with the chosen redirect URL as an allowed redirect URI!
234
+
235
+ ### Example 5: Development from Source
236
+
237
+ When developing or testing local changes:
238
+
239
+ ```jsonc
240
+ {
241
+ "mcpServers": {
242
+ "local-dev": {
243
+ "command": "uv",
244
+ "args": [
245
+ "run",
246
+ "--with-editable",
247
+ "/path/to/authful-mcp-proxy",
248
+ "authful-mcp-proxy",
249
+ "https://mcp.example.com/mcp"
250
+ ],
251
+ "env": {
252
+ "OIDC_ISSUER_URL": "https://auth.example.com",
253
+ "OIDC_CLIENT_ID": "dev-client"
254
+ }
255
+ }
256
+ }
257
+ }
258
+ ```
259
+
260
+ > ⚠️ **Important:** Make sure your OIDC client is configured with `http://localhost:8080/auth/callback` as an allowed redirect URI!
261
+
262
+ ### Example 6: Debug Mode
263
+
264
+ Enable detailed logging for troubleshooting:
265
+
266
+ ```jsonc
267
+ {
268
+ "mcpServers": {
269
+ "debug-server": {
270
+ "command": "uvx",
271
+ "args": [
272
+ "authful-mcp-proxy",
273
+ "--debug",
274
+ "https://mcp.example.com"
275
+ ],
276
+ "env": {
277
+ "OIDC_ISSUER_URL": "https://auth.example.com",
278
+ "OIDC_CLIENT_ID": "my-client-id"
279
+ }
280
+ }
281
+ }
282
+ }
283
+ ```
284
+
285
+ > ⚠️ **Important:** Make sure your OIDC client is configured with `http://localhost:8080/auth/callback` as an allowed redirect URI!
286
+
287
+ ## Using with Other MCP Clients
288
+
289
+ ### MCP Inspector
290
+
291
+ Create an `mcp.json` file:
292
+
293
+ ```jsonc
294
+ {
295
+ "mcpServers": {
296
+ "authful-proxy": {
297
+ "command": "uvx",
298
+ "args": ["authful-mcp-proxy", "https://mcp.example.com/mcp"],
299
+ "env": {
300
+ "OIDC_ISSUER_URL": "https://auth.example.com",
301
+ "OIDC_CLIENT_ID": "inspector-client"
302
+ }
303
+ }
304
+ }
305
+ }
306
+ ```
307
+
308
+ > ⚠️ **Important:** Make sure your OIDC client is configured with `http://localhost:8080/auth/callback` as an allowed redirect URI!
309
+
310
+ Start the inspector:
311
+ ```bash
312
+ npx @modelcontextprotocol/inspector --config mcp.json --server authful-proxy
313
+ ```
314
+
315
+ ### Cursor / Windsurf
316
+
317
+ These editors use the same configuration format as Claude Desktop. Add the server config to your MCP settings file.
318
+
319
+ ### Command Line / Direct Usage
320
+
321
+ ```bash
322
+ # Install globally
323
+ uvx authful-mcp-proxy --help
324
+
325
+ # Run directly
326
+ uvx authful-mcp-proxy \
327
+ --oidc-issuer-url https://auth.example.com \
328
+ --oidc-client-id my-client \
329
+ https://mcp.example.com/mcp
330
+ ```
331
+
332
+ ## Credential Management
333
+
334
+ ### Where Are Credentials Stored?
335
+
336
+ Credentials are cached in `~/.fastmcp/oauth-mcp-client-cache/` with filenames based on the OIDC issuer URL:
337
+ ```
338
+ ~/.fastmcp/oauth-mcp-client-cache/
339
+ └── https_auth_example_com_tokens.json
340
+ ```
341
+
342
+ ### Clear Cached Credentials
343
+
344
+ To force re-authentication (e.g., to switch accounts or clear expired tokens):
345
+
346
+ ```bash
347
+ # Linux/macOS
348
+ rm -rf ~/.fastmcp/oauth-mcp-client-cache/
349
+
350
+ # Windows
351
+ rmdir /s %USERPROFILE%\.fastmcp\oauth-mcp-client-cache
352
+ ```
353
+
354
+ The next time you connect, you'll be prompted to authenticate again.
355
+
356
+ ## Troubleshooting
357
+
358
+ ### Browser Doesn't Open for Authentication
359
+
360
+ **Problem:** The proxy starts but no browser window opens.
361
+
362
+ **Solutions:**
363
+ 1. Check that port 8080 (or your custom redirect port) isn't blocked
364
+ 2. Manually open the URL shown in the proxy logs
365
+ 3. Verify your firewall isn't blocking localhost connections
366
+
367
+ ### 401 Unauthorized Errors
368
+
369
+ **Problem:** Backend MCP server returns 401 errors.
370
+
371
+ **Solutions:**
372
+ 1. Verify `OIDC_ISSUER_URL` matches your provider exactly
373
+ 2. Check that `OIDC_CLIENT_ID` is correct
374
+ 3. Ensure requested scopes are granted by the authorization server
375
+ 4. Clear cached credentials and re-authenticate: `rm -rf ~/.fastmcp/oauth-mcp-client-cache/`
376
+ 5. Enable debug mode to see token details: `--debug`
377
+
378
+ ### Redirect URI Mismatch
379
+
380
+ **Problem:** OIDC provider shows "redirect_uri mismatch" error.
381
+
382
+ **Solutions:**
383
+ 1. Add `http://localhost:8080/auth/callback` to your OIDC client's allowed redirect URIs
384
+ 2. If using a custom port, update both the proxy config (`OIDC_REDIRECT_URL`) and OIDC client settings
385
+ 3. Ensure the redirect URI matches exactly (including trailing slashes)
386
+
387
+ ### Token Refresh Failures
388
+
389
+ **Problem:** Proxy works initially but fails after some time.
390
+
391
+ **Solutions:**
392
+ 1. Check if your OIDC provider issued a refresh token (some providers don't for certain grant types)
393
+ 2. Verify the `offline_access` scope is requested if required by your provider
394
+ 3. Clear cached credentials to get new tokens: `rm -rf ~/.fastmcp/oauth-mcp-client-cache/`
395
+
396
+ ### Connection to Backend Fails
397
+
398
+ **Problem:** Can't connect to remote MCP server.
399
+
400
+ **Solutions:**
401
+ 1. Verify the backend URL is correct and accessible
402
+ 2. Check network connectivity to the backend server
403
+ 3. Ensure the backend server is running and accepting connections
404
+ 4. Try accessing the backend URL directly in a browser to verify it's reachable
405
+ 5. Check for proxy/VPN issues that might block the connection
406
+
407
+ ### MCP Client Doesn't Recognize the Proxy
408
+
409
+ **Problem:** Claude Desktop or other client shows error about the server.
410
+
411
+ **Solutions:**
412
+ 1. Verify JSON syntax is correct (no trailing commas, proper quotes)
413
+ 2. Check that `uvx` or `uv` is in your PATH
414
+ 3. Restart your MCP client completely (not just refresh)
415
+ 4. Review client logs for specific error messages
416
+
417
+ ### Debug Logging
418
+
419
+ Enable debug mode to see detailed information about the authentication flow:
420
+
421
+ ```bash
422
+ uvx authful-mcp-proxy --debug https://mcp.example.com/mcp
423
+ ```
424
+
425
+ Or via environment variable:
426
+ ```jsonc
427
+ {
428
+ "env": {
429
+ "MCP_PROXY_DEBUG": "1",
430
+ // ... other config
431
+ }
432
+ }
433
+ ```
434
+
435
+ ### Still Having Issues?
436
+
437
+ 1. Check the [examples directory](examples/token_validating_mcp_backend/) for a working test setup
438
+ 2. Run with `--debug` to get detailed logs
439
+ 3. Verify your OIDC provider configuration
440
+ 4. Open an issue on GitHub with debug logs (redact sensitive information)
441
+
442
+ # Development
443
+
444
+ ## Setup
445
+
446
+ - Install [Python 3.12](https://www.python.org/downloads) or later
447
+ - Install required development tools:
448
+
449
+ ```bash
450
+ # Install build tools and uv package manager
451
+ python -m pip install build uv
452
+ ```
453
+
454
+ ## Run
455
+
456
+ ### Inside Dev Environment
457
+
458
+ ```bash
459
+ # Create virtual environment
460
+ uv venv
461
+
462
+ # Activate virtual environment
463
+ .venv\Scripts\activate # Windows
464
+ source ./.venv/bin/activate # Linux/macOS
465
+
466
+ # Install project in editable mode with live code reloading
467
+ uv sync
468
+
469
+ # Run the MCP server:
470
+
471
+ # (see --help for CLI options)
472
+ authful-mcp-proxy [options] https://mcp-backend.company.com/mcp
473
+ # or
474
+ uv run --env-file .env authful-mcp-proxy [options]
475
+
476
+ # Stop the server
477
+ # Press Ctrl+C to exit
478
+
479
+ # Deactivate virtual environment when done
480
+ deactivate
481
+ ```
482
+
483
+ ### Outside Dev Environment
484
+
485
+ ```bash
486
+ # Run the MCP server directly from the sources (see --help for CLI options)
487
+ uv run --env-file .env --project "/absolute path/to/authful-mcp-proxy project" authful-mcp-proxy [options]
488
+
489
+ # Run as editable install to enable live code reloading during development (see --help for CLI options)
490
+ uv run --env-file .env --with-editable "/absolute path/to/authful-mcp-proxy project" authful-mcp-proxy [options]
491
+ ```
492
+
493
+ ### With MCP Inspector
494
+
495
+ Create an `mcp.json` file containing:
496
+
497
+ ```jsonc
498
+ {
499
+ "mcpServers": {
500
+ "authful-mcp-proxy": {
501
+ "command": "uv",
502
+ "args": [
503
+ "run",
504
+ "--env-file", // optional, can also be provided via "env" object
505
+ ".env",
506
+ "authful-mcp-proxy",
507
+ "https://mcp-backend.company.com/mcp"
508
+ ],
509
+ // Optional, can also be provided via .env file
510
+ "env": {
511
+ "OIDC_ISSUER_URL": "https://auth.company.com",
512
+ "OIDC_CLIENT_ID": "your-client-id",
513
+ "OIDC_CLIENT_SECRET": "your-client-secret", // optional for public OIDC clients that don't require any such
514
+ "OIDC_SCOPES": "openid profile",
515
+ "OIDC_REDIRECT_URL": "http://localhost:8080/auth/callback"
516
+ }
517
+ }
518
+ }
519
+ }
520
+ ```
521
+
522
+ From a terminal, start the MCP Inspector:
523
+
524
+ ```bash
525
+ # Start and open MCP Inspector in your browser
526
+ npx -y @modelcontextprotocol/inspector --config mcp.json --server authful-mcp-proxy
527
+ ```
528
+
529
+ In your browser, connect to your MCP proxy server, authenticate and use the tools, resources and prompts of the backend MCP server:
530
+ - Connect to MCP proxy server: `Connect`
531
+ - Sign up/sign in and approve required scopes as needed
532
+ - List tools of backend MCP server: `Tools` > `List Tools`
533
+ - Find MCP proxy server logs under `Server Notifications`
534
+
535
+ ### With Minimal Token-Validating MCP Backend Example
536
+
537
+ For quick testing without a real remote MCP server, run the minimal token-validating MCP backend example:
538
+
539
+ ```bash
540
+ # Change to example MCP backend directory
541
+ cd examples/token_validating_mcp_backend
542
+
543
+ # Create virtual environment
544
+ uv venv
545
+
546
+ # Activate virtual environment
547
+ .venv\Scripts\activate # Windows
548
+ source ./.venv/bin/activate # Linux/macOS
549
+
550
+ # Install required dependencies
551
+ uv pip install -r requirements.txt
552
+
553
+ # Run the minimal example MCP client
554
+ uv run --env-file .env mcp_backend.py
555
+ ```
556
+
557
+ ## Check
558
+
559
+ This project uses `pre-commit` hooks for running static checks to maintain high code quality standards. These static checks include:
560
+
561
+ - **Ruff**: Python linting and code formatting
562
+ - **ty**: Modern type checking for Python
563
+ - **Prettier**: JSON, YAML, and Markdown formatting
564
+ - **Codespell**: Common spelling error detection
565
+ - **pyproject.toml validation**: Project configuration validation
566
+
567
+ ### Enable Automatic Execution on Git Commit
568
+
569
+ ```bash
570
+ # Activate virtual environment
571
+ .venv\Scripts\activate # Windows
572
+ source ./.venv/bin/activate # Linux/macOS
573
+
574
+ # Install pre-commit hooks
575
+ uv run pre-commit install
576
+ ```
577
+
578
+ ### Manual Execution
579
+
580
+ ```bash
581
+ # Run all checks on all files
582
+ uv run pre-commit run --all-files
583
+
584
+ # Run individual tools
585
+ uv run ruff format # Code formatting
586
+ uv run ruff check --fix # Linting with auto-fix
587
+ uv run ty check # Type checking
588
+ ```
589
+
590
+ ## Test
591
+
592
+ This project includes a comprehensive test suite to ensure reliability and maintainability of the MCP proxy server functionality. They include:
593
+
594
+ - **Unit tests**: Test configuration, OIDC authentication, and main application components
595
+ - **Integration tests**: Test end-to-end OIDC flows with realistic scenarios
596
+ - **Coverage tracking**: Code coverage reports generated automatically (see `htmlcov/` directory)
597
+
598
+ ```bash
599
+ # Activate virtual environment
600
+ .venv\Scripts\activate # Windows
601
+ source ./.venv/bin/activate # Linux/macOS
602
+
603
+ # Install project dependencies (includes both dev and test groups)
604
+ uv sync
605
+
606
+ # Run all tests
607
+ uv run pytest
608
+
609
+ # Run with verbose output
610
+ uv run pytest -v
611
+
612
+ # Run with coverage report output to terminal and enforce minimum coverage
613
+ uv run pytest --cov=src/authful_mcp_proxy --cov-report=term-missing --cov-fail-under=65
614
+
615
+ # Run specific test file
616
+ uv run pytest tests/test_main.py
617
+
618
+ # Run specific test class
619
+ uv run pytest tests/test_main.py::TestCLI
620
+
621
+ # Run specific test
622
+ uv run pytest tests/test_main.py::TestCLI::test_cli_with_minimal_args
623
+
624
+ # Generate HTML coverage report
625
+ uv run pytest --cov-report=html
626
+ # Open htmlcov/index.html to view detailed coverage
627
+ ```
628
+
629
+ ## Package
630
+
631
+ For publishing to PyPI or integrating with Python package managers:
632
+
633
+ ```bash
634
+ # Activate virtual environment
635
+ .venv\Scripts\activate # Windows
636
+ source ./.venv/bin/activate # Linux/macOS
637
+
638
+ # Install project dependencies
639
+ uv sync --no-dev
640
+
641
+ # Build distribution packages
642
+ uv build
643
+ ```
644
+
645
+ This will create a `dist` folder containing an `authful_mcp_proxy X.X.X.tar.gz` and an `authful_mcp_proxy X.X.X-py3-none-any.whl` file.
646
+
@@ -0,0 +1,10 @@
1
+ authful_mcp_proxy/__init__.py,sha256=dFCv_sFtVPl71RCEHUc_WrLSDMl6iN5cnvcHwMueZG4,264
2
+ authful_mcp_proxy/__main__.py,sha256=Qa808IgE8nqio6QRBeGSdjalvlcj8f0QfAebfTFmNyE,5757
3
+ authful_mcp_proxy/config.py,sha256=nRzPh4-mV5f5hqUomIJjPwpu212nRHvCW-rWOVhG6u4,964
4
+ authful_mcp_proxy/external_oidc.py,sha256=yCkWtR0VskQlXNHQIpVm-TyXxm4XRTWqzAZ1QWIvMGg,16273
5
+ authful_mcp_proxy/mcp_proxy.py,sha256=Cyli_mxcpCIQIsCAR_qjeuDJZlIPyIQy9dpWHhplr1o,2968
6
+ authful_mcp_proxy-0.1.0.dist-info/METADATA,sha256=Z72WM0RJPcap-uiOzw5ing8ZRj4gMV2Lb8xDgj873zo,20933
7
+ authful_mcp_proxy-0.1.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
8
+ authful_mcp_proxy-0.1.0.dist-info/entry_points.txt,sha256=9k_yoK7nvWxY9pnAoZEyxCMjBwO5kQ3ZIIWFBaRYqOc,70
9
+ authful_mcp_proxy-0.1.0.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
10
+ authful_mcp_proxy-0.1.0.dist-info/RECORD,,
@@ -0,0 +1,4 @@
1
+ Wheel-Version: 1.0
2
+ Generator: hatchling 1.27.0
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
@@ -0,0 +1,2 @@
1
+ [console_scripts]
2
+ authful-mcp-proxy = authful_mcp_proxy.__main__:main